Bootstrap a new Myco substrate: creates _canon.yaml (contract + identity + subsystems), MYCO.md (or the named entry-point), and .myco/state/autoseeded.txt at the target project directory. Call this once per project — for every subsequent action, other verbs take over and this one raises "substrate already exists".

Use this when: starting a brand-new substrate for a project that does not yet have _canon.yaml. Do NOT use this when: the project already has a substrate (pulse reports substrate_id), when the workspace has _canon.yaml in a parent directory (you are already inside a substrate), or when you only want to ingest into an existing substrate (use myco_eat instead).

Side effects: writes 3 files (see germination doctrine for the exact canon shape); registers the substrate in ~/.myco/substrates.yaml so myco graft --list-substrates finds it. Honors R6 write_surface (the freshly-stamped canon includes notes/, docs/, src/, .myco/ by default).

Returns: { exit_code, files_created, preview, dry_run, project_dir, substrate_id }. The preview dict shows the first line and byte count of each written file; dry_run=true returns the same shape without writing.

Compose the substrate's hunger report: contract drift (canon version mismatch), raw-note backlog (integer count of notes/raw/*.md pending assimilation), active reflex signals (HIGH/MEDIUM/LOW), concrete next-action advice, and per-kind count of substrate-local plugins. This is the R1 BOOT RITUAL — the mandatory first substantive action every session per the Hard Contract.

Use this: as the FIRST tool call of every session without exception (R1 is a contract rule, not a suggestion). Use it again mid-session whenever the agent wants a fresh state snapshot — it's cheap and idempotent. Do NOT use it as a substitute for myco_brief (which is human-facing markdown, this is agent-facing structured data).

Side effects: none by default. When execute=true, patches <entry_point>'s <!-- MYCO-BOOT-SIGNALS:BEGIN ... END --> block with the current hunger signals, respecting R6 write_surface. On abrupt exit (~1.5s kill budget, SessionEnd hook) prefer myco_senesce with quick=true; hunger itself does not auto-trigger senesce.

Returns: { exit_code, report: { contract_drift, raw_backlog, reflex_signals, advice, local_plugins: { count, count_by_kind, errors, overlay_verbs } }, execute, entry_point_patched }. The substrate_pulse sidecar then tells you which rule to honor next (advances from R1 → R3 after first hunger call).

Ingest raw material into the substrate: one of literal text content, a local file or directory, or an http(s) URL. Writes a markdown file to notes/raw/ with frontmatter (id, source, tags, captured_at). The note enters the raw state of the substrate's metabolism — subsequent myco_assimilate or myco_digest promotes it to integrated.

Use this the MOMENT a decision, friction point, or ingestible artifact appears (R4 of the Hard Contract — "capture insights immediately"). Pass exactly ONE of content/path/url; passing none or more than one is a UsageError. For URLs, install the myco[adapters] extras (PDF, HTML, URL fetchers); the SSRF guard refuses loopback/private/reserved IP ranges (use a text/code file instead when the target is non-public). For path= pointing at a directory, one note is produced per ingestible file found by the adapter registry.

Side effects: creates 1+ files under notes/raw/ (R6-gated by write_surface). Filename pattern: _.md where slug is derived from content/path basename. Atomic O_EXCL create prevents silent overwrites on same-second collisions. merged tags = union(tags, adapter-produced tags), sorted for deterministic output.

Returns (content mode): { exit_code, path, captured_at, tags, source }. Returns (path/url mode): { exit_code, adapter, notes_created, notes: [ { path, captured_at, title, source } ] }.

Perform a keyword substring search across the substrate's markdown + yaml surface and return ranked hits with file path, line number, and snippet. This is the R3 SENSE-BEFORE-ASSERT mechanism: before asserting a substrate fact from training memory, the agent calls this to check ground truth from the substrate itself (R3 of the Hard Contract).

Use this before making any claim about what the substrate contains — e.g. "the substrate says X" should always be preceded by a sense call that returned a hit for X. Fast (no embedding, no LLM, no network) — this is a literal substring scan over notes/, docs/, _canon.yaml, and MYCO.md. For broader semantic search, compose multiple sense calls with different keyword synonyms rather than expanding the query.

Side effects: none. Pure read. Does not touch .myco/state/ or any cache.

Returns: { exit_code, query, scope, hits: [ { path, line, snippet } ] }. hits is ordered by path then line number; snippet is the full matching line trimmed to reasonable width. Empty hits is a successful call with no matches — agent should treat "absence of hit" as "fact not in substrate" per R3.

Enumerate every file under the given path that a Myco adapter can ingest — the "what could myco_eat do here?" preflight. Each returned item includes file path, size, suffix, and the matching adapter's name (text-file, pdf, html, tabular, code-repo, url-fetcher).

Use this before a bulk myco_eat --path= invocation to see what will actually get ingested (and what will be silently skipped because no adapter handles it). Also useful for "what's in this directory" inventory without reading every file's content. Do NOT use this on the substrate root itself recursively — for that, prefer myco_sense or direct filesystem access; forage is for potential-intake surveys.

Side effects: none. Pure read. Adapter registry is walked in import order; more-specific adapters (PDF, HTML, URL) win over the generic text-file adapter.

Returns: { exit_code, target, count, skipped, items: [ { path, size, suffix, adapter } ] }. skipped counts files that matched no adapter (binary blobs, non-text non-code non-document files).

Remove a single raw note from notes/raw/ when it should never have been captured: typo-paste, accidental project_dir routing, duplicate ingest, test data. The note is NOT unlinked — excrete moves it to .myco/state/excreted/.md and annotates its frontmatter with excreted_at, excreted_reason, and excreted_from, preserving an audit trail.

Use this when: you just ran myco_eat and immediately realized the content was garbage, or myco_hunger shows a raw note that should not have been captured. Do NOT use this to remove integrated or distilled notes — those are protected (R4 eat- insights + R7 top-down layering: integrated is a stable lower layer, silent deletion would rewrite history). Attempts to target notes/integrated/ or notes/distilled/ are refused with UsageError. For substantive removal of integrated material, use a myco_fruit craft proposal + myco_winnow review cycle.

Side effects: moves one file from notes/raw/ to .myco/state/excreted/. Writes the moved file with augmented frontmatter. .myco/state/ must be in R6 write_surface (added to template write_surfaces in v0.5.24; existing substrates may need to add .myco/state/** manually to _canon.yaml). Excreted tombstones are gitignored by default.

Returns: { exit_code, note_id, from_path, to_path, reason, excreted_at, dry_run }. exit_code 3 on UsageError (missing note_id, missing reason, or note not in notes/raw/); 0 on success, including dry-run.

Walk a directory, list every adapter-ingestible file via myco_forage, then call myco_eat on each. The atomic bulk-ingest composer that replaces the v0.5.x unimplemented forage --digest-on-read flag.

Single-responsibility composition: forage stays read-only; eat stays single-note; intake is the only verb that composes both with a write side-effect.

Use this when: a fresh substrate needs to absorb an existing directory tree (a paper archive, a code repository, a meeting-log folder). Use --filter regex to select a subset; --max to cap ingest count; --dry-run to preview.

Failure semantics: per-file ingest failures produce a status: failed stub note in notes/raw/ (NOT silent skip; see L0 P2 + AD1 dim) and are reported in the result payload's failures list. --strict mode raises on any failure (exit_code=2).

Side effects: writes 0+ notes to notes/raw/ (one per ingestible file, with frontmatter status=ok|failed). R6 write_surface gated.

Returns: { exit_code, ingested, failed, failures, notes, dry_run }. Use myco_assimilate afterwards to promote the successful raws to integrated.

Promote notes from notes/raw/ to notes/integrated/ — in bulk (all eligible raw notes) or for a single named note. Integrated notes are the substrate's stable knowledge layer; raw notes are the intake queue. A bulk promotion is typical during session-end or before a release: assimilate sweeps the raw queue, re-writes filenames to the n_.md convention, and leaves raw/ empty.

Use this when: raw_backlog reported by myco_hunger is > 0 and you want to integrate the pending captures. Use with note_id= when you want to promote exactly one specific note (e.g. a high-priority decision that needs immediate visibility); for that case myco_digest is the single-note equivalent. Do NOT assimilate before the note is ready (integration is supposed to represent stable knowledge, not half-thoughts).

Side effects: moves files from notes/raw/ to notes/integrated/ (delete + create; atomic). Updates frontmatter (status, promoted_at). R6 write_surface must cover both directories. Errors on a per-note basis are collected and returned; one failed note does not abort the whole batch.

Returns: { exit_code, promoted, already_integrated, errors, outcomes: [ { status, path, dry_run, note_id } ], synced_contract_version_updated }.

Promote exactly one raw note to integrated — the single-note equivalent of myco_assimilate. Used when you need to integrate a specific capture without sweeping the whole raw queue (e.g. a decision that must be visible now while other raw notes need more marination).

Use this when: one specific note must be integrated right now and the rest of the raw queue should stay put. For bulk promotion, use myco_assimilate (same underlying pipeline, no note_id filter).

Side effects: moves one file from notes/raw/ to notes/integrated/. Atomic. Updates frontmatter. R6 write_surface must cover both directories. Fails with exit_code 3 if note_id does not match any raw note.

Returns: { exit_code, status, path, dry_run, note_id }. status is one of: 'promoted', 'already_integrated' (no-op), or raised as UsageError.

Produce a dispersible proposal scaffold by bundling integrated notes into a notes/distilled/d_.md document. The output is a skeleton — frontmatter + source list + empty section headers — which the agent then fills with the actual synthesis prose. Sporulate prepares the substrate's knowledge for external dispersion (propagation to other substrates, or publishing as craft proposals).

Use this when: a body of integrated notes have accumulated that belong together and you want to produce a consolidated view. Do NOT use this expecting auto-synthesis — sporulate builds the container; the agent writes the content. For cross-substrate material sharing, pair with myco_propagate. For substrate-internal contract evolution, pair with myco_fruit (which produces a 3-round craft doc instead).

Side effects: creates 1 file at notes/distilled/d_.md. R6 write_surface must cover notes/distilled/. Filename collision with an existing distilled doc at the same slug is an error (no overwrite).

Returns: { exit_code, path, slug }.

Walk the substrate's cross-reference graph and report health: node count, edge count, src-node count (code files under src/), orphan nodes (no inbound references), dangling edges (point at missing targets), and per-node proposals for reconnection. Anastomosis is the fungal analogy: hyphae (markdown files + references:) fuse into a connected network; orphans + dangling edges are the dead tissue signal.

Use this: periodically (weekly / per-release cadence) to detect knowledge islands forming; before a release to verify docs haven't drifted from code; when debugging "why can't I find X" — dangling edges show what the substrate thinks exists but doesn't. Cheap and read-only — safe to run often.

Side effects: none. Writes a cached graph JSON to .myco/state/graph.json for subsequent traverse calls (bypass with internal use_cache=false). The cache is invalidated by file mtime on re-entry.

Returns: { exit_code, scope, orphans: [...], dangling: [...], proposals: [...], node_count, edge_count, src_node_count, cached }.

Copy integrated and/or distilled notes from this substrate to a downstream target substrate's notes/raw/. The receiver's agent then chooses which to assimilate — propagate is the source-side push; the receiver's own metabolism filters. Today's integrated-in-A becomes tomorrow's raw-in-B (per L0 principle 4: 永恒迭代, today's conclusion is tomorrow's raw material).

Use this when: knowledge produced in substrate A should feed substrate B (cross-project knowledge sharing). Do NOT use this as a replacement for git (propagation is a knowledge artifact movement, not version-control). The receiver must have a valid _canon.yaml at dst; propagation refuses if dst is not a substrate (no auto-germinate).

Side effects: writes 1+ files under /notes/raw/ on the DOWNSTREAM substrate (not this one). R6 write_surface check is applied to the destination substrate's canon, not the source. Dry-run available.

Returns: { exit_code, select, src_substrate_id, dst_root, count, propagated: [...source paths...], compat_warnings, dry_run, commit }.

Run the substrate's 50 lint dimensions and report findings (severity + category + location + message per finding). Dimensions fall in four categories: mechanical (canon invariants, write-surface coverage, LLM-boundary), shipped (package version ↔ canon version parity), metabolic (raw-note backlog, stale integrated), semantic (graph connectedness, orphan detection). Per L2 homeostasis.md, this is the substrate's autonomic health check.

Use this: routinely during development (cheap, ~1-2s), at release time (R7 top-down layering checks); with fix=true to auto-repair mechanically-fixable findings (M2 entry-point, MB1 raw_backlog). Do NOT use this to validate external code hygiene — immune only checks substrate contract invariants, not application correctness (that's what pytest is for).

Side effects: none by default. With fix=true, applies safe repairs per each dimension's fixable contract: M2 creates missing entry-point stubs, MB1 can auto-assimilate raw notes over threshold. All fixes respect R6 write_surface. List-mode

• explain-mode are pure read.

Returns: { exit_code, findings: [...], dimensions_run, skeleton_downgrade_applied, exit_on, fix, fixes: [...] }. exit_code 0 when no critical findings; non-zero otherwise.

Put the session into dormancy: run a reflect pass (which may promote raw notes, update integrated frontmatter, and patch boot_brief.md). In full mode (default), also run myco_immune --fix to repair any mechanically-fixable findings the session produced. This is the R2 SESSION-END RITUAL per the Hard Contract.

Use this: at session end BEFORE compaction (PreCompact hook calls this with quick=false — full mode). On abrupt exit with a tight kill budget (~1.5s, SessionEnd hook), pass quick=true — reflect only, skip immune; the next SessionStart catches up. Do NOT skip this at session end: without senesce, the raw queue backs up across sessions and reflex signals go stale.

Side effects: may write to notes/integrated/ (promotions), boot_brief.md (signal refresh), and trigger full immune --fix in default mode (which may write to various R6-allowed paths). In quick=true mode: reflect only, no immune.

Returns: { exit_code, findings: [...], reflect: { promoted, errors, outcomes }, immune: { dimensions_run, skeleton_downgrade_applied, exit_on, fix, fixes }, mode }.

Scaffold a new 3-round craft proposal doc under docs/primordia/craft.md with the canonical three-round debate structure (Round 1 claim → 1.5 self- rebuttal → Round 2 revision → 2.5 counter-rebuttal → Round 3 reflection/decision). This is how Myco governs architectural change: every contract or doctrine evolution flows through a fruiting cycle before it lands.

Use this when: an architectural change needs governance (new verb / dimension / subsystem / contract rule). The agent fills in the tensions and revisions, then myco_winnow gates the shape. Do NOT use this for feature requests or bug reports (those go in notes/raw/ via myco_eat); fruit is for substrate-level evolution decisions only.

Side effects: creates one file at docs/primordia/craft.md. R6 write_surface must cover docs/primordia/. Filename collision with existing primordium at same slug+date is an error (bump date or pick a new slug). Agent is expected to fill in the template fields after scaffolding.

Returns: { exit_code, path, slug, kind, date, rounds, status }. status is 'DRAFT' on scaffold; agent flips to 'LANDED' once winnow passes.

Ship a contract-version bump: update _canon.yaml's contract_version and synced_contract_version fields to the new value, append a stub section to docs/contract_changelog.md with placeholders, and advance waves.current counter. The atomic molt keeps all three version knobs in lockstep and produces a reviewable one-commit diff.

Use this AT RELEASE TIME, not during development. Pair with .scripts/bump_version.py which orchestrates molt alongside the package-version bump in init.py, plugin.json, and CITATION.cff. Do NOT call this mid-session for ad-hoc experiments — the contract_changelog is append-only and reverting a molt requires an explicit down-bump.

Side effects: writes _canon.yaml + docs/contract_changelog.md. R6 write_surface must cover both. Dry-run prints the diff that would be applied. Skip-molt option in bump_version.py exists for cases where the version parity step is separate from the canon stamp.

Returns: { exit_code, new_version, synced_touched, waves_touched, canon_path, changelog_path, canon_preview_head }.

Gate a docs/primordia/ craft proposal against the craft protocol shape: 3 (or 5) rounds present, required sections (Claim / Self-Rebuttal / Revision / Counter-Rebuttal / Reflection) populated, frontmatter keys complete, body is not mostly template boilerplate (> 40% boilerplate triggers G6), etc. Returns pass/fail verdict and specific violations.

Use this: after fruit scaffolds a craft doc and the agent fills in the tensions and revisions — winnow tells whether the proposal has enough substance to land. Do NOT use winnow as a content quality check (it checks STRUCTURE, not whether the argument is good). For content review, human judgment still applies.

Side effects: none. Pure read.

Returns: { exit_code, proposal, verdict: 'pass'|'fail', round_count, body_chars, violations: [ { gate, message } ], frontmatter_keys }. exit_code 0 on pass, 1 on fail. Agents typically fix violations and re-winnow until pass before declaring a craft 'LANDED'.

Scaffold the code skeleton for a new extension point: a manifest verb, a lint dimension, or an ingestion adapter. Writes a stub file into the appropriate location — either src/myco/ (kernel, for core Myco evolution) or /.myco/plugins/ (substrate-local, for project- specific extensions). Auto-detects substrate-local mode when the substrate is not the myco-self kernel substrate.

Use this when: an agent or operator wants to add a new verb / dimension / adapter without hand-writing boilerplate. Exactly ONE of verb/dimension/adapter must be specified; combining raises UsageError. Do NOT use this to modify existing plugins — ramify is scaffold-only, refuses to overwrite unless --force.

Side effects: creates one Python file at the computed target path. R6 write_surface must cover the target; for substrate- local mode, .myco/plugins/ must be in the substrate's write_surface. Dimension mode also requires category + severity; adapter mode requires extensions list.

Returns: { exit_code, mode, , class, category, severity, path, written, overwritten, substrate_local }.

Introspect the substrate's plugin surface: list every loaded dimension / adapter / schema_upgrader / overlay_verb with (kind, name, source, scope), validate plugins by re-importing under isolation, or explain a single plugin (source path + docstring). Scope classifies each plugin as 'kernel' (shipped with myco package) or 'substrate' (loaded from /.myco/plugins/).

Use this when: debugging "why is my plugin not loading", auditing what's actually registered, or listing substrates across the machine (--list-substrates mode, reads ~/.myco/substrates.yaml). Do NOT confuse with myco_immune's dimension-listing mode — graft inspects plugin binaries, immune inspects findings.

Side effects: none. Pure read. --validate mode does re-import plugins, which executes their init.py; the execution occurs in an isolated module namespace and is idempotent — safe even for plugins that register into global registries.

Returns (by mode). --list: { exit_code, mode:'list', plugins: [...], count }. --validate: { exit_code, mode: 'validate', errors: [...] }. --explain: { exit_code, mode: 'explain', name, kind, source, scope, docstring }. --list-substrates: { exit_code, mode:'list-substrates', substrates: [...], count, live_count, stale_count }.

Produce a human-facing markdown rollup of substrate state: hunger summary, immune findings, note counts by layer, recent primordia, local-plugin inventory, and a "suggested next" action list. Per L0 principle 1 ("Only For Agent"), this is the single carved exception where Myco authors human-facing prose — every other verb's output is primary material for the agent alone.

Use this when: a human operator wants to glance at substrate state (weekly / release-time check-in). For agent-to-agent reporting prefer hunger (structured) or the substrate_pulse sidecar (automatic on every verb). Do NOT use brief as an input to other verbs — it's a terminal rollup, not a structured protocol surface.

Side effects: none. Pure read. Output goes to stdout as markdown; agent / human reads, nothing is written.

Returns: { exit_code, markdown: '...' }. The markdown string is the full rollup; callers print it or surface it in UI as-is. No other fields beyond exit_code + markdown.