Initialization

SASE initialization commands create or refresh durable files that agents and companion tools rely on. Bare sase init checks the current project and home setup first, then either reports that everything is current or shows the initializers that need attention:

sase init -c       # report drift without writing
sase init          # prompt before each needed initializer
sase init --yes    # run every needed initializer in order

The coordinator plans in registry order: AMD, memory, SDD, then skills. Planning is read-only. In non-interactive shells, bare sase init reports drift and exits non-zero instead of prompting; use sase init --yes when you want an unattended apply run. Apply runs can write project files, deploy home files through chezmoi when configured, and use each initializer's normal commit/push behavior. Bare sase init only lets AMD generate managed project AGENTS.md content when the current project's own ./sase.yml sets amd_h1_title; explicit AMD commands still repair provider shims and handle legacy one-file migrations when that field is unset.

Explicit subcommands are still available when you need narrower control:

sase amd init --check
sase amd init
sase amd list
sase init amd --check
sase memory init --no-commit
sase memory init --check
sase memory list
sase memory review --list
sase memory log
sase memory log --include proposals
sase memory log --path long/generated_skills.md
sase memory log --id <read-id>
sase memory episodes build -n <agent-name>
sase memory episodes auto -p <project> -l 50  # one checkpointed maintenance pass
sase memory episodes build -s 2026-05-01 -u 2026-05-26 --split
sase memory episodes recall -q "retry feedback"
sase init sdd
sase init sdd --check
sase skills list
sase skills init --dry-run

# Agent-side audited operations, normally run from a SASE-launched agent:
sase memory read long/generated_skills.md --reason "Need generated skill context"
sase memory write --title "Generated skills" --slug generated_skills --evidence chat:abc123 --body "Durable memory body" --notify

Start with sase init -c, sase amd init --check, or sase memory init --check when you only want a drift report. After that, sase memory init --no-commit is the usual first apply run for memory because it writes the generated files but skips the project git commit/pull/push path. It is not a dry run: it can still write project files, write home memory, and follow home-level use_chezmoi deployment. sase init amd remains a compatibility alias for sase amd init, sase init memory remains a compatibility alias for sase memory init, and sase init skills remains a compatibility alias for sase skills init.

Commands

Command	Purpose
sase init	Check AMD, memory, SDD, and skills; prompt once per needed initializer in interactive shells.
sase init -c, --check	Report initialization drift without writing and exit non-zero when changes are needed.
sase init --yes	Run every needed initializer in AMD, memory, SDD, skills order without prompting.
sase amd	Alias for sase amd list.
sase amd list	Inspect project, home, and chezmoi AGENTS.md files and nearby provider shims.
sase amd init	Create or refresh AGENTS.md files and provider shims for the selected AMD root or roots.
sase amd init --check	Report AMD initialization drift without writing files.
sase init amd	Compatibility alias for sase amd init.
sase memory	Alias for sase memory list.
sase memory list	Inspect loaded, referenced, available, and missing memory files for the current root.
sase memory read <path>	Agent-side read of one long-term memory file with an attributable audit event.
sase memory write	Create an attributable long-term memory proposal for human review.
sase memory review	List, inspect, approve, edit, or reject pending memory proposals.
sase memory log	Summarize audited long-term memory reads.
sase memory log --include proposals	Include proposal and review events in the memory audit surface.
sase memory log --path <path>	Show a path-level summary and matching individual read events.
sase memory log --id <read-id>	Show one full audited read event by id or unambiguous id prefix.
sase memory episodes	Build, inspect, maintain, verify, export, and recall source-linked evidence records.
sase memory init	Create or refresh project/home memory roots and AGENTS memory references.
sase memory init --check	Report memory initialization drift without writing files.
sase memory init -C	Write memory files but skip the project git commit/pull/push path.
sase init memory	Compatibility alias for sase memory init.
sase init sdd	Alias for sase sdd init; enables version-controlled SDD and refreshes generated guides.
sase init sdd --check	Report SDD config and generated-file drift without writing files.
sase skills	Alias for sase skills list.
sase skills list	Inspect generated skill sources, provider targets, and deployed-file drift without writing.
sase skills init	Generate skill files; existing files require confirmation or --force.
sase skills init --dry-run	Preview generated skill target paths without writing files.
sase skills init --force	Generate and overwrite deployed skill files without confirmation.
sase skills init -p <provider>	Deploy only one provider's generated skill files.
sase init skills	Compatibility alias for sase skills init.

Advanced deploy controls such as --no-commit, --no-push, and --no-apply live on explicit subcommands rather than the bare coordinator. Scoped --check flags also live on explicit subcommands when you want to validate only memory or only SDD generated files.

Agent Markdown Documents

AMD is the initialization surface for agent markdown documents: root AGENTS.md plus provider shims such as CLAUDE.md, GEMINI.md, QWEN.md, and OPENCODE.md.

sase amd list
sase amd init --check
sase amd init
sase init amd --check

With no subcommand, sase amd defaults to sase amd list. The inventory shows project, subdirectory, home, and chezmoi-source AGENTS.md files, their H1 titles, whether they look AMD-managed, short/long memory reference counts, and nearby provider shim status.

sase amd init plans against the current directory unless use_chezmoi: true adds or redirects to the chezmoi home source root. It always creates or repairs provider shims for each selected root. Project-local provider shims contain @AGENTS.md; direct live-home provider shims contain an absolute import such as @/home/bryan/AGENTS.md. Chezmoi home source shims are managed as CLAUDE.md.tmpl, GEMINI.md.tmpl, QWEN.md.tmpl, and OPENCODE.md.tmpl files containing @{{ .chezmoi.homeDir }}/AGENTS.md, which render to absolute imports on each machine. When a selected ordinary root has a local ./sase.yml with amd_h1_title, AMD writes a managed AGENTS.md with marker-delimited short-memory and long-memory sections. When the selected root is the live home root, a user config value from ~/.config/sase/sase.yml or ~/.config/sase/sase_*.yml can provide the home AGENTS.md title. When the current directory is the chezmoi home source root, AMD reads the source-side dot_config/sase/sase.yml and dot_config/sase/sase_*.yml files instead, so edited dotfile source config can drive source AGENTS.md generation before chezmoi apply.

With use_chezmoi: true, running sase amd init from the live home root initializes the chezmoi home source root instead of writing ~/AGENTS.md directly. Running it from any other directory initializes that directory and the chezmoi home source root, deduplicating roots that resolve to the same path. A global or user-level amd_h1_title still does not opt ordinary roots into managed AGENTS.md; each ordinary root must set the title in its own ./sase.yml.

When no applicable title is configured and AGENTS.md is missing, explicit AMD init can migrate exactly one custom provider instruction file into AGENTS.md; multiple custom provider files block so content is not guessed.

Bare sase init runs AMD before memory so memory validation can see the AGENTS.md that AMD would create. To avoid surprising existing repositories, bare sase init only lets AMD generate managed AGENTS.md when the current project's own ./sase.yml opts in with amd_h1_title; global config values are ignored for this generator.

Memory Initialization

sase memory init initializes both project-local and home-level memory surfaces:

• Project memory under ./memory/, including memory/README.md, memory/short/sase.md, and memory/long/.
• Home memory under ~/memory/, or under ~/.local/share/chezmoi/home/ when use_chezmoi: true.
• A minimal AGENTS.md when one does not already exist and the repo is not opted into AMD-managed instructions.
• Provider shims CLAUDE.md, GEMINI.md, QWEN.md, and OPENCODE.md; project roots contain @AGENTS.md, while direct live-home roots contain absolute @/path/to/home/AGENTS.md imports. Chezmoi home source roots use *.md.tmpl provider shim sources containing @{{ .chezmoi.homeDir }}/AGENTS.md.

When the project-local ./sase.yml sets amd_h1_title, sase memory init synchronizes the AMD-managed memory blocks inside AGENTS.md, adds missing description frontmatter to long-memory files, and renders the Tier 3 list from those descriptions before reachability validation runs.

When use_chezmoi: true, the home files are written to the chezmoi source tree. The command can then commit those home changes and run chezmoi apply --force; --no-commit does not disable that home deployment path.

The generated memory/short/sase.md summarizes workspace naming and sibling repositories. Project memory reads sibling repo descriptions from the project-local ./sase.yml; home memory reads them from the global config ~/.config/sase/sase.yml, or from the chezmoi-managed config path when use_chezmoi: true. Generated memory distinguishes static-path siblings (workspace.strategy: none) from numbered-workspace siblings, lists the direct path for static siblings, and includes sase workspace open instructions only when at least one configured sibling uses numbered workspace resolution.

Every configured sibling_repos entry must have a non-empty description. Initialization fails instead of generating ambiguous memory when a description is missing.

By default, project memory initialization runs the configured precommit command, stages generated project files, commits them with the standard memory-init commit message, pulls with rebase, and pushes. Use sase memory init --check for a read-only drift check, or sase memory init --no-commit when you want to review generated project files before committing. --no-commit only skips the project deploy path; home memory deployment still follows use_chezmoi when it is enabled.

Memory validation is reachability-based: Markdown files under memory/short/ and memory/long/ must be reachable from AGENTS.md directly or through transitive @memory/... or memory/... references. Unreferenced memory files make the command fail so important agent context is not silently ignored.

Memory Context List

sase memory list, or bare sase memory, renders a read-only dashboard for the current directory. It reports:

• loaded files reached by transitive @... references from AGENTS.md in the project or home context.
• referenced files mentioned by plain memory/... text from loaded context, or by memory-relative long/... paths in audited sase memory read instructions. These are visible in the dashboard, but their contents are not loaded unless another @... edge reaches them.
• available files present under project or home memory/short/ and memory/long/ that the current launch context does not reach.
• missing referenced memory paths that do not exist.

The dashboard includes approximate local token estimates for loaded memory context.

For day-to-day read/write operations, including audited reads and reviewed long-term memory proposals, see Memory.

Memory Read Audit Log

sase memory read <memory-relative-path> -r <reason> is the audited path for agent-initiated long-term memory reads. The path is relative to memory/; the command allows Markdown files under memory/long/ and rejects memory/short because short-term memory is expected to arrive through instruction loading. The command strips one leading YAML frontmatter block from stdout, but the audit log records only metadata such as path, agent name, timestamp, cwd, byte count, and reason.

Every read must include a non-empty reason via -r or --reason. The command also requires agent attribution from SASE_AGENT_NAME, SASE_AGENT, or SASE_ARTIFACTS_DIR/agent_meta.json; unattributed reads fail instead of writing a log row. Human shell users normally inspect files directly and use sase memory review for promotion decisions.

sase memory write creates an attributable proposal under ~/.sase/projects/<project>/ and never writes memory/long/*.md directly. It uses the same agent-attribution rules as read; --manual-author is intended for tests and demos. Pass --notify when you want a best-effort memory.proposed notification in the SASE inbox. sase memory review is the human promotion path for listing, showing, approving, editing, or rejecting those proposals.

sase memory log reads the project-scoped audit log from SASE state under ~/.sase/projects/<project>/, not from the repo. Use --path or --agent to drill down to matching read events, --id <read-id> to inspect one event, and --json for deterministic machine-readable output. Add --include proposals to include proposal and review ledger events alongside read-log summaries.

# read requires SASE agent identity; write requires agent identity unless --manual-author is used for demos
sase memory read long/generated_skills.md --reason "Need generated skill context"
sase memory write --title "Generated skills" --slug generated_skills --evidence chat:abc123 --body "Durable memory body" --notify
sase memory review --list
sase memory log
sase memory log --include proposals
sase memory log --path long/generated_skills.md
sase memory log --id <read-id>

SDD Initialization

sase init sdd is an alias for sase sdd init. It creates or updates the project-local sase.yml with sdd.version_controlled: true, then creates or refreshes generated SDD guide files and sdd/assets/sdd-directory-map.png for either a project root or an SDD root:

sase init sdd
sase init sdd --check
sase init sdd --path ./sdd

Keep conceptual SDD documentation in docs/sdd.md. The files generated by sase init sdd are intentionally short project-local guides and are safe to overwrite. Use --check to compare the project config and generated files without rewriting them.

Built-in bare-git projects run this same generated-file refresh automatically during sase git init, existing bare-repo registration, workspace materialization, and the first version-controlled SDD write. Manual sase init sdd is still useful when you want an explicit refresh or a drift check.

Skill Initialization

Generated skills start as xprompt sources marked with a skill frontmatter field. sase skills list is the read-only inventory: it shows loaded skill sources, the providers they target, and whether generated SKILL.md files are current, stale, or missing. Bare sase skills shows the same dashboard.

sase skills init renders those sources into provider-specific SKILL.md files. Sources include bundled skill xprompts and user/runtime xprompt catalog entries. The usual workflow is to inspect first, preview writes, then deploy:

sase skills list
sase skills init --dry-run
sase skills init --force

Without use_chezmoi, generated skill files are written directly under the provider's home-directory skill targets. When use_chezmoi: true, skill initialization writes through the chezmoi-managed home tree and can commit, push, and apply those dotfile changes. The --no-commit, --no-push, and --no-apply flags only affect that chezmoi deployment sequence. sase init skills still works as a compatibility alias for sase skills init.

See XPrompt Skill Field for the skill-source contract and bundled skill list.