# Avatar Manual

> Use for an unfamiliar or consequential Avatar spawn, shallow/deep choice, detached lifecycle, recovery, or footprint review. Routine schema-sufficient spawns can use the tool directly.

- Skill: `lingtai-ai/avatar-manual` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add lingtai-ai/avatar-manual`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lingtai-ai/avatar-manual/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lingtai-ai (https://skillmd.com/u/lingtai-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lingtai-ai/avatar-manual

---


# Avatar Manual

Avatar creates a **persistent, independent peer** as a detached process. Use
`daemon` for disposable work and `shell` for a one-off command. After launch,
communicate by mail/email; there is no ongoing Avatar handle.

## Routine spawn: direct path

The schema is enough for a routine call; do not load this manual as a ritual.
Use all five strict spawn-input keys and put the mission in root `reasoning`:

```text
avatar(action="spawn",
       input={"name": "researcher", "type": null, "comment": null,
              "dry_run": false, "confirm": false},
       reasoning="Inspect the heartbeat regression; report evidence by mail and change no code.")
```

State objective, resources, reporting route, done condition, and constraints.
`name` is the canonical sibling basename, not a separate display name. Spawn
creates an independent life: obtain authorization, and do not batch it with
unrelated calls. `dry_run=true` previews without writes or a process, **not**
launch admissibility; `confirm=true` acknowledges only mission review.

| Need | Read |
|---|---|
| Payload choice, exact mission/name gates, preview limits, comment/preset inheritance | [Spawn and identity](reference/spawn.md) |
| Boot result, detached life, authority, platform, failed launch, retirement | [Lifecycle and authority](reference/lifecycle.md) |

`avatar(action="manual", input={}, reasoning="load Avatar guidance")` returns
this **package-local** body and `manual_path`; resolve its links from that path,
not from an Agent's installed skill copy. Avatar has no rules action or fan-out:
use `psyche(action="manual", input={}, reasoning="locate rules guidance")` for
the kernel/Psyche `.rules` protocol.

## Read-only settings

`avatar(action="settings", input={}, reasoning="inspect Avatar policy")`
returns 16 fresh five-field rows: `key`, `current`, `default`, `configurable`,
`comment`. Every row is fixed, `current=default`, `configurable:false`.
The source is `tools/avatar/settings.py`; there is no Avatar settings file,
`LINGTAI_AVATAR_*` override, or set/reset action. Per-call inputs do not change
SHOW. Changing fixed policy requires an authorized source change, tests and
owner relaunch, then SHOW again. Values are public policy, not identity,
credentials, environment contents, or live session state. An unavailable row
fails the whole action as bounded `SETTINGS_UNAVAILABLE`, without partial rows.

### Spawn call defaults

`type` is `shallow`, `comment` is empty, `dry_run` and `confirm` are false when
nullable inputs are omitted/null. These four rows describe call defaults only.
Shallow copies rewritten init plus narrow Psyche inputs; deep adds durable
identity/knowledge state. See the payload reference before assuming isolation.

### Spawn validation policy

Five rows: allowed types `shallow`/`deep`; name minimum 1 and maximum 64
characters; mission minimum 20 trimmed characters; placeholder tokens `bar`,
`check`, `debug`, `foo`, `temp`, `test`, `tmp`. Names use Unicode-aware
`^[\w-]+$` plus explicit length/dot checks: supply letters/digits/underscore/
hyphen only. Exact mission token/space behavior is in the spawn reference.

### Spawn lifecycle policy

Seven rows: boot wait 5.0 seconds, poll 0.1 seconds, stderr tail 2,000 bytes;
preset policy `parent-default`, environment `inherit-launcher-process`,
lifecycle `detached-independent`, and admin inheritance `none`.
Heartbeat presence is not a freshness or human-delivery proof; raw stderr may
be sensitive. The lifecycle reference owns result/error and authority details.
Preset rewriting is conditional on a configured default; see spawn reference.

## Cleanup / Footprint

Targets are sibling `<network-root>/<name>/` and the parent's append-only
`delegates/ledger.jsonl`, not cache. For read-only counts/bytes, the packaged
[shared footprint recipe](../../skills/manual/reference/cleanup-footprint-contract.md#shared-footprint-check-recipe)
accepts explicit target paths and writes/deletes nothing. Consider a report
after an avatar-heavy session or before retirement; logging it to
`logs/cleanup.jsonl` is optional and requires consent.

Never delete directories, ledger, active processes, or recovery/audit state
blindly. Capture a handoff, check current liveness, report footprint, then seek
exact authorization for the specific lifecycle or destructive action. If the
user is unavailable, stop after the report.