snuffle installs and runs through npx (no daemon, no account). The one-liner npx @snuffle/cli setup scans the agent config directories in your home (~/.claude, ~/.codex) for the skills, subagents, and MCP servers you already use, previews them, and on confirmation records each as canon at your user scope under ~/.snuffle/user/<kind>/. It writes a default ~/.snuffle/config.json if one is absent.

setup is dry-run-first: with no apply signal it writes nothing and just shows the candidates. In an interactive terminal it asks "index these at your user scope? [Y/n]"; in CI or a non-TTY you pass --apply (or -y) to skip the prompt. Every rendered resource is secret-scanned before it is written — user scope is the one scope where an explicit # snuffle:allow directive is honored. It then offers to onboard the current project too (or run it up front with --project).

Once imported, these follow you everywhere: snuffle mcp merges your user scope on serve, so your global skills and MCP servers are available in every project you later onboard. snuffle publishes to npm as @snuffle/cli, so npx @snuffle/cli setup always runs the latest without a global install.

snuffle onboard integrates an existing repo in one command. It scaffolds .snuffle/ (via snuffle init), discovers existing agent config and docs — .claude/skills, CLAUDE.md, docs/adr, .cursor/rules — and imports them as canon, reusing anything your user scope already covers by reference instead of copying. It wires the snuffle MCP server into .mcp.json, installs the operating-skill pack into .claude/skills/, installs the decision-before-merge gate (a GitHub Action plus a lefthook pre-push), and wires the advisory agent-side gate hook into .claude/settings.json.

In a terminal you get to edit the selection before anything is imported: it lists the candidates and offers [Y] import all, [n] none, or [e] edit — confirming each one. An agent or CI run imports all. Secret-bearing files are skipped, never copied into canon. Re-running is idempotent: existing files are left untouched and the surgical edits re-apply as no-ops.

An agent can do the same over MCP: the installed snuffle-onboard-project operating skill runs the flow, and the agent then reports what it imported, reused, and skipped. onboard also offers optional, free-by-default AI steps (drafting strategy, learned embedder, drift classification) that are skipped silently when non-interactive.

Onboard wires Claude by default. To make a second agent behave the same way, connect it to the same .snuffle store and install the same operating skills in its own native format — nothing is migrated or copied, both agents resolve one playbook over MCP.

snuffle cursor init wires .cursor/mcp.json and installs the operating skills as .cursor/rules/snuffle-*.mdc. snuffle codex init registers the server in the global ~/.codex/config.toml and installs prompts under ~/.codex/prompts/. snuffle claude init does the Claude equivalent (.mcp.json + .claude/skills/). Each of these commands also accepts refresh and sync (re-apply the projection to current canon) and remove (unwire). snuffle link re-creates the MCP projections for whichever agents the project already uses.

After this, Claude Code, Cursor, and Codex read the same resolved playbook — same skills, same rules, same order of work — each in its own format. Reload the agent to pick up the wiring.

On the CLI, snuffle ask "<question>" answers from your own canon without leaving the terminal. It is extractive, not generative: it builds the effective KB (project + your user scope + resolved references), runs the same hybrid lexical+vector search the MCP semantic_search tool uses, and returns the top-ranked resources as citations (scope:id + relpath) plus the leading snippet of the best match. Pass --k N to widen the result set. Prose synthesis over the hits would need a hosted LLM and is deliberately not wired.

Your coding agent reaches the same knowledge over MCP — it starts snuffle mcp on demand, which serves this project's .snuffle store merged with your user scope. The agent uses the read tools (semantic_search, structured_filter, graph_traverse, fetch_resource, assemble_context, context_for_file, overview) to pull the right canon into context, and the write tools (record_skill, record_decision, record_rule, record_workflow) to capture new knowledge as you work — governed by the installed operating skills like snuffle-load-context, snuffle-answer-from-canon, and snuffle-record-decision.

snuffle doctor checks the base's health and clean-exit status and flags reusable skills and rules that live only in this project and are worth lifting to user scope.

When you onboard your next repo, anything already covered by your user scope is reused by reference, not copied — you get the same behavior without the copy-paste. To make a project-only resource follow you everywhere, snuffle promote <ref> relocates its bytes to the user home store (~/.snuffle/user/<kind>/) and leaves a body-less source: reference stub in the project. The promoted resource then loads as user scope on every serve and is reused by reference.

promote is fail-closed. It refuses (writing nothing) when the ref is not at project scope, is already a reference, is a governed kind (rule/hook — promoting would invert team precedence), is a decision (append-only project provenance), when --to is anything but user, when the body holds a secret, or when the rewritten content would not re-parse. It is idempotent and clobber-safe: re-promoting byte-identical content is a no-op, and a different existing user file is never overwritten.

An agent can do this through the snuffle-promote operating skill after snuffle doctor flags a reusable resource.

A team in snuffle is your device's signing key pinned as the owner trust-root plus a shared store — there is no service to run. snuffle team create <name> --broker <store-url> pins this device's keychain-backed public key as the team's owner trust-root (written to .snuffle/config.json) and prints its fingerprint; publish that fingerprint out-of-band so a first joiner can confirm it. The private key never leaves the keychain.

snuffle team invite --allow <emails> --ttl-days <n> mints a signed redemption code that pre-approves the listed emails; --open makes it a bearer token anyone can redeem (defaulting to a shorter 1-day TTL). Only the pinned owner key can mint invites. The invite prints a npx snuffle join <code> line to hand to the joiner.

On the joiner's machine, snuffle join <code> verifies the code against the pinned owner key (a first join requires an out-of-band fingerprint confirmation via --pin-owner-key <fp>), then drops a signed pending request — their public key, never their secret — into the shared store. Nobody is admitted until the owner approves: snuffle team pending lists the queue and snuffle team approve <email> appends an owner-signed membership event that binds the joiner's device key. Self-asserted email is a label, not a control — membership is conferred only by the owner's signature, so holding the shared-store credential alone cannot mint a member.

snuffle sync reconciles team-scope canon (.snuffle/team/**.md) with the configured backend (fs or Scaleway) using a hash-based 3-way merge against a manifest in .snuffle/state/sync/. When an owner trust-root is pinned, every team file is signed on push and verified on pull against the owner-signed member set: an unsigned file, or one signed by an unknown or unapproved signer, is held back before it touches your repo. Egress is fail-closed — every local team file is secret-scanned before any push, and one hit aborts the whole sync.

Both-sides-changed cases surface as conflicts and exit non-zero unless you force a winner with local-wins or remote-wins. --watch runs it as a daemon (with --interval N), and --git-snapshot records a snapshot. When a project needs a different take on a team skill, a project-scope copy overrides it for that repo alone while team rules and hooks stay enforced.

An agent runs this through the snuffle-share-with-team operating skill and reports what it pushed, pulled, and held back.

Offboarding never holds your markdown hostage. snuffle detach --team <name> removes the team from this project's config and keeps its local store frozen (history and attribution preserved) — --purge wipes that local store instead. snuffle detach --project unwires every agent (each package tears down its own MCP entry), strips projected rule blocks, removes the advisory Claude gate hook, and deletes derived state, leaving .snuffle/project/** and .snuffle/team/** markdown intact. snuffle detach --device drops this device's signing key from the keychain. snuffle uninstall does the full local teardown at once (project wiring + derived state + device key), still keeping markdown unless you pass --purge.

Detach is honest about revocation: dropping local config or creds cannot revoke server-side grants. To actually cut off a leaver's or a leaked credential's access to shared canon, the owner rotates the shared store credential — snuffle team rotate-credential prints the manual out-of-band checklist (mint a new key, distribute to current members, delete the old one). Self-detach is reversible: re-run snuffle <agent> init to re-wire.

snuffle is a shared "how-we-build" knowledge base for AI coding agents. The playbook itself is nothing exotic: it is plain markdown files with YAML frontmatter, one file per resource, living under a .snuffle/ folder. Those files are the single source of truth ("L0 canonical"). You can open, grep, diff, and commit them; if you deleted snuffle entirely you would still have a readable folder of markdown. Nothing needs snuffle to make sense.

The playbook lives at three scope directories that are just subfolders: project canon in .snuffle/ inside your repo (versioned in git); user canon under ~/.snuffle/user/ (your promoted resources, following you across projects); and team canon mirrored from a shared store under ~/.snuffle/teams/<name>/. Within a scope, resources are organized by kind (e.g. user/workflows/feature-delivery.md, team/decisions/0046-*.md, user/skills/*.md).

The platform's job is to move these files between machines (git in your repo, plus the team store), index them, and serve the ranked, task-scoped slice to agents and humans over a local MCP server, with inheritance/override across user then project then team scopes. The architecture is layered and each layer is pluggable: L0 canonical files, L1 sync (files to/from a bucket), L1.5 reconcile (git 3-way, union-merge the append log), L2 index (Postgres + pgvector + FTS), L3 access (the MCP toolset with a file-only fallback), L4 resolution (inheritance/override/drift), and L5 governance (declarative workflows, gates, decision log). Set up a project with snuffle init.

Every resource has a kind, from a fixed vocabulary of eight: skill, command, rule, hook, workflow, decision, spec, note (RESOURCE_KINDS in packages/core/src/domain/kinds.ts). workflow and decision are the hero kinds — the differentiator — capturing repeatable multi-step processes and the append-only reasoning log.

Frontmatter is validated by a zod schema (packages/core/src/canonical/frontmatter.ts). Core fields: id (stable logical id; derived from the file path minus the scope prefix if absent), kind, title, description, scope (inferred from a leading user/ project/ team/ path segment if absent), tags, status (free-form, e.g. a decision's status: accepted), and lifecycle. Kind-specific and feature fields include: phases (workflow steps, each with resources refs and gates); command (a hook's executable command — a hook whose command is not an allowlisted-safe snuffle … invocation is high-risk and gets quarantined until approved); applies_to (repo-root-relative posix globs the resource governs — an agent editing a matching file pulls it as the relevant "why"); owners (CODEOWNERS-style approvers); supersededBy (successor for the "use X instead" nudge); overrides (target + baseHash, drives drift); source (by-reference stub pointing at the canonical copy); promotedFrom; and decision provenance (deciders, supersedes, backfilledFrom, draftedBy).

Lifecycle is an explicit lifecycle: field (absent → active), deliberately separate from the free-form status:. There are five states (packages/core/src/domain/lifecycle.ts): draft (hidden from consumers, not pushed, not surfaced), active (normal), deprecated (still findable but de-ranked to 0.5x and warned with a "use X instead"), archived (removed from the index and the active sync set, but history kept — still directly fetchable), and quarantine (behaves like draft — hidden, not synced, not indexed — but is assigned by admission for a high-risk hook, not authored, and stays inert until snuffle approve clears it). Only active + deprecated are indexed, surfaced, and synced.

A single logical id can be defined at more than one scope. Resolution collapses each id to exactly one effective winner, and which scope wins is kind-dependent (packages/core/src/resolution/resolve.ts). This is deliberate and deterministic — no LLM involved.

Governed kinds (rule and hook) are the team's enforceable canon, so the shared base wins: precedence is team > project > user. A user can refine a rule within a project, but cannot quietly override a team mandate from their own user scope. Everything else (skills, commands, workflows, decisions, specs, notes) is personalizable, so the most-specific scope wins: user > project > team. Decision 0012 records that the original uniform user > project > team ordering — which let a user silently shadow a team rule/hook — was a correctness bug.

Cross-scope reuse without copying is done by-reference. snuffle promote <ref> lifts a project resource's canonical bytes into your user home store (~/.snuffle/user/<kind>/) and leaves a body-less source: reference stub in the project; the loader materializes the stub's body from the target so the bytes live in exactly one place, and the promoted resource follows you into every project. Promote is fail-closed: it refuses non-project-scope refs, already-references, governed kinds (promoting a rule/hook to user would invert team precedence), decisions (append-only project provenance), a --to other than user, a body holding a secret, or content that would not re-parse.

Two questions get conflated constantly, and the whole model turns on keeping them apart (docs/design/access-model.md). First: how does the playbook get to a machine/project/team? Answer: files. git in your repo, plus the team store. Not MCP. Second: how does an agent read and write the playbook while it codes? Answer: MCP — local, on-demand, scoped and ranked.

L0/L1 is files. In a repo the .snuffle/ folder travels with git like any other tracked files. Across projects, snuffle promote lifts a resource into your user scope (by reference). Across a team, snuffle sync pushes/pulls signed canon through a store you own (S3-style bucket) — signed on push, verified against the owner-approved member set on pull. MCP is never the sync transport; a teammate's changes reach you as files in the store.

L3 is MCP. The server is local and stdio, launched on demand by the agent's host (packages/core/src/mcp/start.ts, StdioServerTransport) — there is no resident daemon and no remote endpoint. At serve time it does the work raw file reads can't: it merges user + project + team scopes, materializes source: references, and resolves the effective kind-aware canon before anything reaches the agent, then builds the search index over that same effective set; fail-closed secret scanning runs on the serve path. The result is the right resolved slice for the task, not the whole corpus and not an unresolved pile of per-scope files.

What is always materialized into agent-native folders is narrow: the MCP config (.mcp.json, .cursor/mcp.json, ~/.codex/config.toml, generated not symlinked) and the eleven snuffle-* operating skills that teach each agent how to use snuffle. The rest of your domain canon (skills, workflows, decisions, specs, notes) is NOT re-projected back to native folders — it is served over MCP. The one opt-in exception is rule projection (below).

The knowledge base is writable over MCP. When capture is enabled, the server advertises four record tools and emits capture instructions to the agent (packages/core/src/mcp/server-factory.ts): record_skill (a reusable how-to, the moment you learn a repeatable technique), record_decision (a consequential choice — the what, the why, the trade-offs — which also satisfies the decision-before-merge gate proactively; omit the body to get a MADR scaffold), record_rule (a must/never the team should always follow, with optional appliesTo code-path globs so the rule code-anchors to the files it governs), and record_workflow (a repeatable multi-step process, phases required, each phase optionally carrying gates).

All four write plain markdown into the project store at project scope. The sink is fail-closed: it validates and secret-scans before the write lands — so you never paste credentials, you reference them. There is deliberately no record_note tool (notes are freeform/low-signal for agents; the four kinds cover the authoring surface), though note capture still works programmatically.

Capture is gated by write authorization: the tools are registered only when a capture sink is injected and the principal has write on the project (with the default AllowAll backend this is permissive). The equivalent CLI surface for humans is snuffle decision (scaffold a decision-log entry).

The governance layer (L5) is a decision-before-merge gate plus an advisory nudge. snuffle gate diffs the changeset against a base ref (--base, else $GATE_BASE, else origin/main) and passes if and only if the changeset adds or modifies a kind: decision resource — exit 0 when satisfied, 1 otherwise (packages/cli/src/commands/gate.ts). This is the same check the GitHub required status check runs (authoritative) and that lefthook runs at pre-push (advisory shift-left). There is also snuffle gate --hook, a Claude Code PreToolUse mode: it reads the tool payload on stdin and, for a publish command (git push / gh pr create|merge) with no decision recorded on the branch, returns a deny nudging you to record one — advisory only, it never hard-blocks (the forge required check is the authority).

Hard gates can also be declared on workflow phases: a phase's gates entry of type: hard (with an optional machine check, e.g. decision-exists) is compiled to a forge check; type: soft gates are agent-followed.

The nudge (snuffle nudge) is purely advisory and always exits 0: when significant work is about to be pushed with no decision recorded, it prints the exact snuffle decision command to run while it's fresh (packages/cli/src/commands/nudge.ts). It is wired as an advisory pre-push lefthook command and surfaced in snuffle doctor; nudge.enabled: false fully silences it. Related surfaces: snuffle coverage reports undocumented reasoning (changes with no decision, thin-coverage areas) and snuffle backfill proposes decision entries for un-recorded architectural history.

A teammate can join a team and receive its canon without the owner standing up any external service — no operated broker, no GitHub OAuth app, no Postgres, no OpenFGA (docs/design/team-distribution.md). The only requirement is a shared storage backend (the existing Storage seam — local fs for solo, S3/Scaleway for a real team). Identity and credential-minting are pluggable seams with a zero-config local default and OAuth/OIDC/STS as later opt-ins.

The trust model is the Discord/Slack "invite link + admin approval" pattern. An invite is a signed (ed25519) bearer join-request token carrying an allow list of pre-approved emails or the literal "any", inside the signed payload. Identity is self-asserted (read from the joiner's local gh/git). In the zero-config build every join QUEUES — auto-join is enabled only behind a verified IdP. The security gate is the approval queue plus the owner: a leaked code lets someone request to join under a claimed identity; the owner seeing an unexpected identity and denying is what stops the leak.

Membership state lives in the shared store, not a server: membership and the pending queue are an append-only log of immutable, content-addressed objects (key = hash of the event), folded by mergeAppendLog so distinct keys never collide. Every membership-mutating event (approve/deny/revoke, member record) is ed25519-signed by a key chained to the team's pinned owner trust anchor and verified on read; unsigned/untrusted events are ignored. snuffle sync push signs each file into a content-addressed sidecar; pull builds the canon trust root (owner key + approved members' bound device keys) and rejects unsigned, unknown-signer, or secret-bearing content.

The honest caveat, stated plainly in the design: v1 closes forgery, not confidentiality. Byte-level read of the store is gated by the storage credential, not by approval — any shared-cred holder can read/write/delete all canon regardless of membership, and deny/revoke cannot rescind it; the only v1 revocation is rotating the shared credential (a documented team rotate-credential checklist, since the CLI reads SCW_* from env and cannot rotate the IAM key). Scoped per-user credentials (the STS/minter seam, decision 0099) are the prerequisite for sensitive canon and per-user revocation.

MCP retrieval depends on the agent choosing to call a tool. Rule projection is the opt-in stronger guarantee: it materializes the resolved always-on rule set into each wired agent's native always-on rule surface, so a must-follow rule is in context with zero tool calls (docs/design/specs/rule-projection.md). It is off by default (projection.enabled), keeping the MCP-first model intact for everything else. Only kind: rule is projected — skills, commands, workflows, decisions, specs, and notes stay MCP-only.

The projected set is kind === "rule" from the effective, authz-filtered KB, filtered to surfaced lifecycle (draft/archived/quarantine excluded; deprecated labeled). Because it is the resolved set, a project or user scope cannot shadow a team rule via projection — governed rules are team-wins (decision 0012) and only the winner per id is emitted. applies_to is the always-on axis: a rule with no applies_to is projected everywhere; a rule with applies_to globs becomes Cursor-only (one .mdc per rule with native globs: + alwaysApply: false), since Claude/Codex have no glob-gated always-on surface.

Targets: Claude's project-root CLAUDE.md and Codex/generic AGENTS.md get a delimited managed block (<!-- BEGIN SNUFFLE RULES (managed; do not edit; checksum=…; created-by-snuffle=…) --> … <!-- END SNUFFLE RULES -->), mirroring the Supbuddy convention and co-existing with it; Cursor gets .cursor/rules/snuffle-rules/<id>.mdc. The merge is surgical: content outside the block (including a co-resident Supbuddy block) is preserved byte-for-byte. The set is secret-scanned on egress (fail-closed, all-or-nothing) before any write. The honest trade-off: a projected rule is a checksummed COPY of canon in a committed file — drift is detected (via the checksum), not auto-healed; project-rules/link/sync regenerate (canon wins), a hand-edit inside the block is reported then replaced, and hand-edits outside the block always survive.

There are two distinct drift axes. The first is override drift (L4, packages/core/src/resolution/drift.ts). An override resource records the upstream content hash it was based on (overrides.baseHash); the tripwire compares that against the upstream's current hash. It is a high-recall tripwire, not a verdict — a status of upstream-changed just means "look closer" (the semantic classifier + conversational HITL of a later phase decide whether the override is actually stale). Statuses are ok, upstream-changed, upstream-missing, and no-base. Detection has two surfaces: a pull-time full scan (every override checked against current upstreams, scanDrift) and a push-time preflight that only re-checks overrides referencing the upstreams that just changed (driftAffecting). It is wired into the sync pipeline.

The second axis is projection drift (from rule projection): each projected managed block carries a checksum, and snuffle doctor (plus snuffle project-rules --check) recomputes the on-disk block's inner checksum and compares it both to the recorded marker checksum (hand-edit drift) and to freshly-resolved canon (staleness). This readout is advisory — it prints a line but never flips doctor's exit code — and staleness is computed through the identical resolver + projectRules path that a real projection would use, so doctor's verdict cannot disagree with what project-rules would actually write.

Secret scanning is a fail-closed gate on every write/egress surface (packages/secrets/src/scan.ts). scanText runs the default rule set over the content and returns findings that never carry the secret value — only rule id, description, 1-based line, column, and the matched length. A scanner that echoed secrets to logs/JSON would itself be a leak, so this is a deliberate invariant; formatHits output is therefore safe to display.

The scan runs before capture writes land (the MCP record tools), on sync push and — after review hardening — symmetrically on every pull (including solo/dev, no key needed), on snuffle promote, and on the rule-projection egress (the final on-disk bytes of every artifact, aborting the whole projection on any finding before any write). Because resolution materializes source:/override bodies, the scan runs on the resolved bytes, not just the on-disk source.

The one escape hatch is a # snuffle:allow directive on the matched line (or a standalone comment line directly above it), and it is honored only when the caller passes allowDirectives — which the code does solely for user-authored, user-scope content. A team or project resource can never whitelist its own secret, and a projected file (a shared artifact) is scanned like team scope. The honest limit: scanText is a credential detector, not a prompt-injection or display sanitizer — that is separate, harder work.

The MCP toolset is a progressive search surface (R21): start cheap and broad, drill only where it pays. overview (totals + counts by kind/scope + flat summaries) is the entry point; structured_filter filters by kind/scope/tags (must match ALL)/free text; graph_traverse walks [[wikilink]] / phase / override edges from a ref to a given depth and direction; and fetch_resource is the deep-fetch step (full body + frontmatter) used last. context_for_file returns the rules/specs/skills that declare a path via applies_to globs, ranked most-specific first — deterministic, no search needed, meant to be called before editing a file (its human twin is snuffle why). assemble_context seeds via hybrid search, expands one hop over the reference graph, ranks, then packs to a token budget (full body, else summary, else dropped) — extractive, no synthesis (the human twin is snuffle pack). All of these except semantic search work file-only with no index, so the server is useful offline.

Semantic search is the hybrid layer. semantic_search is registered only when an index is available (otherwise callers gracefully fall back to the file-only tools). It fuses a vector ranking and a lexical ranking via Reciprocal Rank Fusion (packages/core/src/index/rrf.ts) — RRF combines ranked lists without needing comparable scores (score = sum of 1/(k+rank), k=60). The index is built with snuffle index (Postgres + pgvector + FTS).

The embedder is pluggable and the default is free and offline: a HashingEmbedder. snuffle embed setup opts into a learned embedder — local (Ollama, free) or remote (OpenAI / Voyage) — storing non-secret config only (provider/model/base URL/dimensions and the env-var NAME of the key, never the key). embed test embeds a probe and reports observed dimensions; embed show prints resolved settings without the key. Because switching providers changes vector dimensions/identity, a persisted index must be rebuilt with snuffle index afterward. snuffle ask answers from your own canon with ranked citations.

snuffle serves your .snuffle/ canon to a coding agent over the Model Context Protocol on stdio. The server is stood up by snuffle mcp (defined in packages/cli/src/commands/mcp.ts): stdout is the MCP protocol channel and all logs/readiness go to stderr. Under the hood it loads the project store (merging your user-scope canon and any resolved team references), builds a KbService (packages/core/src/mcp/service.ts), and registers the toolset from createKbMcpServer (packages/core/src/mcp/server-factory.ts). Before it will start it runs a fail-closed secret scan of the store and refuses to serve if any credential is found.

You don't launch snuffle mcp by hand day-to-day. You wire it into an agent once with snuffle claude init, snuffle cursor init, or snuffle codex init. Each writes a server entry (npx -y snuffle mcp) into the agent's MCP config file (.mcp.json for Claude Code, .cursor/mcp.json for Cursor, Codex's TOML for Codex). From then on the agent boots snuffle automatically and the tools appear namespaced (e.g. mcp__snuffle__semantic_search).

The toolset degrades gracefully by capability. The four progressive-search tools (overview, structured_filter, graph_traverse, fetch_resource) plus context_for_file and assemble_context are always registered. semantic_search is registered only when a semantic index is available (service.hasSemanticSearch()). The capture/write tools (record_skill, record_decision, record_rule, record_workflow) are registered only when a capture sink is injected AND the principal has project write — a read-only serve simply omits them.

When capture is enabled the server also emits MCP instructions (the CAPTURE_INSTRUCTIONS string). This is guidance the agent reads on connect: it tells the agent the KB is writable, to call record_skill when it learns a reusable technique, record_decision for consequential choices (which also satisfies the decision-before-merge gate proactively), record_rule for a must/never, and record_workflow for a repeatable process — and that everything written is secret-scanned, so reference credentials, never paste them.

overview is the cheapest first call in progressive search. It returns totals, counts broken down by kind and scope, and a flat list of lightweight resource summaries. The intent is: start here to see the shape of the canon, then narrow with structured_filter or graph_traverse before you ever fetch a full body. It takes no arguments and calls service.overview().

structured_filter narrows the canon by metadata: kind (one or many), scope (one or many), tags (must match ALL supplied), and/or free text matched across id, title, and description. It returns lightweight summaries only — not full bodies. It is the deterministic narrowing step after overview and is stronger for precise metadata than free-form search. Backed by service.filter().

graph_traverse starts from a resource ref (a bare id like skills/foo or a scoped team:rules/base) and walks the reference graph — [[wikilink]], phase, and override edges — out to a given depth (1–5, direction outgoing/incoming/both). It returns the reached resource summaries each tagged with its distance from the start. It's how an agent discovers what a given piece of canon connects to (or what points at it). Note: quarantined resources are not discoverable by traversal — they're only reachable by an explicit direct ref. Backed by service.graphTraverse().

fetch_resource is the only tool that returns full content: the complete body plus frontmatter for a resource ref (id or scope:id). It's deliberately the last step — you narrow with the cheap tools first, then deep-fetch the one or few resources you actually need. Backed by service.fetch(); returns whether it was found and the resolved full resource(s).

semantic_search runs a hybrid search — vector plus lexical, fused via Reciprocal Rank Fusion — over resource text, returning ranked summaries with scores. Use it when you don't know exactly where to look; then narrow with structured_filter / graph_traverse and fetch_resource. Deprecated resources are de-ranked (still findable, sort below equivalents); draft/archived never reach the index. This tool is only registered when a semantic index is available.

The CLI cousin is snuffle ask "<question>", which builds the effective KB (project + your user scope + references) and runs the same hybrid RRF search, returning the top resources as citations plus the leading snippet of the best match. It is extractive — no LLM prose synthesis.

context_for_file takes one or more file paths and returns the rules/specs/skills that govern them via their applies_to globs — ranked most-specific first, each with a snippet of the why. It's deterministic (pure metadata + glob, no search or LLM). The guidance is to call it BEFORE editing a file so the relevant policy and reasoning load into context. Decisions also surface when the project's coverage-map (.snuffle/coverage-map.json) anchors them to the path. Backed by service.contextForFile().

The CLI cousin is snuffle why <path> [<path>...], the human side of the same tool — same deterministic glob-anchored lookup, including coverage-map-anchored decisions.

assemble_context takes a task or area description and assembles a curated, token-budgeted bundle of the most relevant canon. It seeds via hybrid search, expands one hop over the reference graph, ranks, then packs to the token budget — full body where it fits, else summary, else dropped — returning ordered resources, citations, and a drop list. It is extractive: it selects and packs canon, it does not synthesize prose. Inputs: task (required), tokenBudget (256–200000), and optional kind/scope filters, seedK, and expandDepth. Backed by assembleContextPack().

The CLI cousin is snuffle pack "<task>" [--budget N] [--kind K] [--scope S]. It reuses the ask load path; a semantic index sharpens the seeds but isn't required (it degrades to a lexical fallback).

record_skill captures a reusable technique as a plain-markdown skill in the project knowledge base (project scope). The MCP instructions tell the agent to call it the moment it learns a repeatable technique. Inputs: title (required), body (required markdown), optional description, optional tags. What lands on disk: a file at project/skills/<slug-of-title>.md with id skills/<slug>, frontmatter (kind: skill, id, title, scope: project, plus description/tags when given), and the body. Before it's written the content is validated to round-trip through the loader's parser and is secret-scanned (fail-closed) — a captured file can't poison the next load, and credentials are rejected. Registered only on a writable serve.

record_decision captures a consequential decision — the what, the why, the trade-offs — as an append-only decision-log entry, and proactively satisfies the decision-before-merge gate. Inputs: title (required), optional body, optional deciders. If you omit the body, snuffle writes a MADR scaffold (Context / Decision / Consequences) for you to fill in. What lands on disk: an auto-numbered file project/decisions/NNNN-<slug>.md (append-only sequence) with id decisions/NNNN-<slug>, frontmatter including status: proposed and any deciders. Secret-scanned and parser-validated before write. Registered only on a writable serve.

record_rule captures a rule — a must or never the team should always follow — as plain markdown at project scope. Inputs: title (required), body (required), optional description, optional tags, and optional appliesTo code-path globs. When you supply appliesTo, the rule code-anchors to the files it governs (which is exactly what context_for_file / snuffle why later surface for those paths). What lands on disk: project/rules/<slug>.md with id rules/<slug>, frontmatter (kind: rule, scope: project, plus applies_to globs when given). Secret-scanned and parser-validated before write. Registered only on a writable serve.

record_workflow captures a repeatable multi-step process as a workflow (a hero kind) at project scope. The one required structural input is phases — at least one — each with a name and optional description, referenced resource ids, and optional gates (each gate has id, type soft|hard, description, and an optional check). Also accepts title (required), optional body, description, and tags. What lands on disk: project/workflows/<slug>.md with id workflows/<slug>, a rendered phases: YAML block (including any gates), and frontmatter. The parser rejects a phase-less workflow, and content is secret-scanned and parser-validated before write. Registered only on a writable serve.