@rayul/kordis 0.15.1 → 0.16.0

package/NOTICE

@@ -31,4 +31,4 @@ package and is not licensed with it.
     where no keychain is available.
   * `KORDIS_API_URL` points the CLI at a different host.
   * Error telemetry is off unless turned on, carries no identity, and is
-    described in the repository's CLAUDE.md.
+    described in the repository's `docs/security.md`, under "Error telemetry".

package/assets/AGENTS.md

@@ -0,0 +1,108 @@
+# packages/skills — the agent guidance both CLIs ship
+
+Markdown that an agent on a user's machine reads and acts on. It is not a pnpm
+package (no `package.json`, no scripts): the two CLIs copy it into their npm tarballs
+at build time, and their `setup` commands install it into the user's agent tools.
+These files are the product's user documentation; a reader who gets a wrong command
+from them runs it in front of a user.
+
+## Scope
+
+- `MEMGINEERING.md` — the memgineering hub. `memgineering setup` strips its
+  frontmatter and injects the body between `<!-- memgineering-start -->` and
+  `<!-- memgineering-end -->` into `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` and
+  `~/.gemini/GEMINI.md` (and writes it as its own file under `~/.grok/rules/`). It is
+  in context for every session of every one of those tools.
+- `memgineering-*` — seven sub-skills (`memory` is the map from question to verb;
+  `recall`, `writing`, `rules`, `setup`, `registry`, `installing` carry the detail),
+  installed into each tool's `skills/` directory and loaded by description match.
+- `KORDIS.md` — the hub of the older `kordis` CLI, injected between
+  `<!-- kordis-start -->` and `<!-- kordis-end -->` by `kordis setup`.
+- `kordis-*` — six sub-skills. `kordis setup` installs five; `kordis-memory` stays
+  in the repo and is drift-checked but is not installed, because its commands are
+  registered only under `KORDIS_EXPERIMENTAL_MEMORY=1`.
+
+## Not in scope
+
+- The behaviour these files describe and the code that installs them:
+  `apps/memgineering` (`src/brand.ts`, `src/commands/setup.ts`) and `apps/cli`
+  (`src/brand.ts`, `src/commands/setup.ts`). Change the code there, the words here,
+  in the same change.
+- `apps/memgineering/assets/` and `apps/cli/assets/`: gitignored build output that
+  every build deletes and recopies. Never edit them.
+- Contributor documentation; these files are written for users' agents.
+
+## How the files ship
+
+- `pnpm -F memgineering build` copies `MEMGINEERING.md` and every `memgineering-*`
+  directory into `apps/memgineering/assets/` (`apps/memgineering/scripts/copy-skills.mjs`).
+  `pnpm -F @rayul/kordis build` copies this whole directory into `apps/cli/assets/`.
+- In both CLIs the hub file's presence in `assets/` is how the program tells a
+  published install from a source checkout; without it, `setup` reads this
+  directory directly.
+- A user's installed copy changes only when they upgrade the CLI and `setup` runs
+  again. A fix here does not reach anyone until a release.
+
+## Invariants
+
+- Every command, subcommand and flag a file names exists in the CLI that ships it.
+  `memgineering <verb> [<subcommand>] --flag` is checked against the program
+  `apps/memgineering` builds; `kordis <verb> --flag` against `kordis <verb> --help`.
+  Every backticked `snake_case` identifier in a kordis file must exist as a key or
+  string literal in the source of `packages/contracts`, `packages/harness-schema`,
+  `packages/memory-engine`, `apps/mcp` or `apps/cli`.
+- memgineering files spell the registry as `memgineering registry <verb>`. The flat
+  top-level aliases still work and are never taught.
+- The set of `memgineering-*` directories equals `BRAND.subSkills` in
+  `apps/memgineering/src/brand.ts`, in both directions, and the hub names every one.
+  A new sub-skill is a directory, a `BRAND.subSkills` entry and a hub mention.
+- Directory names are permanent. `setup` has no delete path, so a renamed sub-skill
+  leaves the old one on users' machines teaching the old surface.
+- The `MEMGINEERING.md` body (after frontmatter) stays under 5,000 characters with no
+  fenced code blocks. It sits two characters under the cap, so any addition moves
+  text into a sub-skill; phrases already moved into `memgineering-writing` are pinned
+  by the drift test and may not disappear.
+- `MEMGINEERING.md`'s `version:` frontmatter equals `apps/memgineering/package.json`
+  `version`; bumping the CLI means bumping this line. `KORDIS.md` carries its own
+  `version:` (0.2.0) that nothing ties to a package.
+- memgineering files are English only (no Hangul anywhere, triggers included), and
+  no shipped file contains an absolute home path (`/Users/...`, `/home/...`) or a
+  real person's name or conversation. The kordis files' descriptions carry Korean
+  trigger phrases on purpose.
+- The hosted connector URL in `memgineering-setup/SKILL.md` and in the hub equals the
+  one documented in `apps/mcp/README.md` and `HOSTED_CONNECTOR_URL` in the setup
+  command.
+- The hub and `memgineering-writing` both keep the rule that a stored fact is one
+  that was checked, not worked out.
+- A behaviour change in either CLI updates the matching file here in the same
+  change, and that release's changelog gets an `### Agent guidance` subsection: root
+  `CHANGELOG.md` (both language halves) for `KORDIS.md` and `kordis-*`,
+  `apps/memgineering/CHANGELOG.md` for the memgineering files.
+
+## Writing patterns
+
+- The hub routes; sub-skills explain. The hub holds only what must be true before
+  any skill loads, because it is paid for in every session.
+- A sub-skill keeps its frontmatter (`name`, `description`, `type`,
+  `allowed-tools`). The description says when to load it, lists trigger phrases and
+  says what it is not for — tools pick skills by that text alone.
+- When guidance has to override what a model assumes by default, state the negation
+  outright ("It does NOT wait for them") rather than only the fact.
+- Commands are written for the agent to run on the user's behalf, not as
+  instructions for the user to type; the reader may be someone who has never opened
+  a terminal.
+
+## Tests
+
+There is no test runner here; the suites that check these files live in the CLIs.
+
+- `pnpm -F memgineering test`, or `test:unit` (what CI's unit job runs) — both build
+  first, which recopies these files into `assets/`; `src/skill-drift.test.ts` covers
+  the memgineering files. Vitest run without that build checks whatever `assets/` an
+  earlier build left, not these files.
+- `pnpm -F @rayul/kordis test` — `src/__tests__/skill-doc-drift.test.ts` spawns
+  `kordis <verb> --help` through tsx for every verb the kordis files mention; it is
+  slow by design and has a two-minute per-test ceiling.
+- Read `Test Files N passed` for each package. A drift failure names the file and
+  the command or flag that does not exist; fix the guidance or the CLI, never the
+  test's verb list alone.

package/assets/MEMGINEERING.md

@@ -2,7 +2,7 @@
 name: memgineering
 description: Use whenever the user refers to something they told you before, asks what was decided, tells you something worth keeping, or settles something that should hold next time. The memory lives in their own folder and outlives this session; check it before answering from guesswork, and write to it when you learn something durable.
 type: skill
-version: 0.21.0
+version: 0.27.0
 ---
 
 # memgineering
@@ -83,6 +83,8 @@ at six skills, each of which loads on its own when its topic comes up:
 - `memgineering-registry` — the public layer
 - `memgineering-installing` — putting a package in their project, and updating it
 
+Not shell-only: ChatGPT and Claude.ai reach a hosted brain via connector `https://mcp.memgineering.com/mcp`.
+
 A host short on room lists a skill by NAME ONLY, no description — measured on
 Claude Code. When you cannot see what it covers, READ
 `<tool-home>/skills/memgineering-<name>/SKILL.md` before deciding it is empty.

package/assets/kordis-publishing/SKILL.md

@@ -20,19 +20,46 @@ Publish a valid, AI-review-passing version. ALWAYS dry-run first.
 - `license` — SPDX (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`).
 - Optional: `homepage`, `tags`, `type`.
 
-**`type` auto-inference (0.6.4+):** The CLI infers `type: skill` when
-you push a directory bundle, a `.skill` ZIP, OR a single file named
-`SKILL.md` or `*.skill.md`. You don't need to write `type:` in the
-frontmatter for any of these paths. Use `--type <t>` (or write the
-field manually) only when pushing a different package type from a
-single `.md` file that doesn't match the SKILL.md filename pattern.
+**`type` and `--type`:** A package is published as the type its
+frontmatter's `type:` says, and nothing else. When the frontmatter has
+no `type:` line, the CLI writes one in: `type: skill` for a directory
+bundle, a `.skill` ZIP, or a single file named `SKILL.md` or
+`*.skill.md` — so none of these needs `type:` written — or `type: <t>`
+when you pass `--type <t>`, on any path. When the frontmatter names a
+type, `--type` must say the same: a different value is refused before
+anything is sent (`usage_error`, exit 2, in `--dry-run` too). Change the
+frontmatter's `type:`, or drop `--type`.
+
+Nothing is written over a `type:` line that is already there, or into a
+file that begins with a byte-order mark. These fail instead, in
+`--dry-run` too; write `type: <t>` in by hand:
+
+- `type:` with no value (or `null`, a number, a list), and a file with a
+  byte-order mark and no `type:` line: `missing_required_frontmatter`
+  (exit 30), with or without `--type`.
+- `type: ""`, an empty string: without `--type` it fails as
+  `unknown_type` (exit 30); with `--type` it disagrees, so it is refused
+  before anything is sent (`usage_error`, exit 2).
+
+**Older CLIs (0.15.2 and earlier)** send `--type` only beside the
+content and never write it in. They fill in `type: skill` themselves
+when the frontmatter names no type: for a folder or `.skill` bundle
+from 0.1.12, and for a single `SKILL.md` or `*.skill.md` from 0.6.4.
+The registry refuses a `--type` that differs from the type it reads —
+written or filled in — with `usage_error` (exit 2) and a hint naming
+that type. From 0.2.2 their `--dry-run` checks the file locally and
+sends no publish request (from 0.9.1, `--bump minor` or `major` makes
+it look the package up), so it does not show this refusal; only a real
+push does. 0.2.1 and earlier send the dry run to the registry, which
+refuses it the same way as a real push. Writing `type:` in the
+frontmatter works on every version.
 
 **`version` field handling:**
 
 - **First publish** — used as-is (else defaults to `0.1.0`).
 - **Update** — the registry computes the next version from
   `current_version + --bump <strategy>` (default `patch`). If the file's
-  `version` differs from that result, the API rejects with `usage`. Either
+  `version` differs from that result, the API rejects with `usage_error`. Either
   drop the `version` field on updates, set `--bump` to match, or align
   them.
 - RECOMMENDED: **omit `version:` from frontmatter on update pushes** and
@@ -70,8 +97,11 @@ get rejected. Dry-run first like any push.
 ## Recording lineage (0.12.0+)
 
 When a package descends from another (especially a judgment you adapted), record
-the provenance on `push` so it shows up in the "Derived from / Adapted by" graph,
-feeds the `community-adapted` trust tier, and gives a small trending boost:
+the provenance on `push`. It shows up in the "Derived from / Adapted by" graph,
+and when the derivative is another author's — public, with its current version
+passed review — it also feeds the source's `community-adapted` trust tier and
+gives the source a small trending boost. A derivative of a package you authored
+yourself does neither. Record it with one of these flags:
 
 | flag                    | edge kind    | meaning                                         |
 | ----------------------- | ------------ | ----------------------------------------------- |
@@ -80,10 +110,13 @@ feeds the `community-adapted` trust tier, and gives a small trending boost:
 | `--absorbs <slug>`      | `absorption` | folds the source in as one part                 |
 | `--remixes <slug>`      | `remix`      | recombines multiple sources                     |
 
-Unresolved sources (typo'd / unpublished slug) are **skipped fail-open** — the
-publish still succeeds and the response's `lineage.skipped` lists them so you
-can fix the slug or publish the source first. Declare lineage honestly; it is
-the registry's trust signal, not decoration.
+A source that does not resolve — a typo'd slug, or a package that is
+unpublished, deleted or private — **refuses the whole publish** with
+`usage_error` (exit 2), and nothing is written. `--dry-run` does not look
+sources up, so a typo first shows on the real push. Fix the slug, or publish
+the source first, then push again. (Naming your own package as its source is
+skipped instead, and listed in the response's `lineage.skipped`.) Declare
+lineage honestly; it is the registry's trust signal, not decoration.
 
 ## Yanking a bad version (0.10.0+)
 
@@ -160,7 +193,7 @@ operator restores it.
 | `--dry-run`                                                           | validate only; do not publish                          |
 | `--bump <strategy>`                                                   | `patch` (default) / `minor` / `major` — only on update |
 | `--slug <slug>`                                                       | override slug on first publish                         |
-| `--type <type>`                                                       | override type inference                                |
+| `--type <type>`                                                       | fills a missing `type:`; must match an existing one    |
 | `--changelog <text>`                                                  | optional changelog entry attached to this version      |
 | `--no-wait`                                                           | return immediately without waiting for AI review       |
 | `--adapted-from <slug>` / `--forked-from` / `--absorbs` / `--remixes` | record lineage (see "Recording lineage")               |
@@ -171,33 +204,66 @@ operator restores it.
 
 ### 1. Dry-run
 
-`kordis push <file> --dry-run --json`. Returns the same validation, conflict,
-and version-resolution verdicts a real push would produce.
-
-CAVEAT: dry-run does NOT exercise the AI reviewer — it short-circuits with
-a synthetic `review.result: "passed"` (`prompt_version: "stub-v0"`). Treat
-dry-run as syntactic + structural validation only. A real push routes
-through the AI review worker, which can land terminal `passed` /
-`rejected`, OR leave the publish in `status: "pending"` if the worker
-hasn't decided within the wait window.
-
-**Success criteria**: dry-run returns a `status: "published"`-shaped envelope
-with no error flags.
-
-### 2. Resolve flags
-
-Possible verdicts:
-
-- `validation_failed` (exit 30) — fix every listed flag, re-dry-run.
+`kordis push <file> --dry-run --json` runs on this machine (0.2.2+): it
+sends no publish request and needs no sign-in. It validates the content
+the real push would send — the frontmatter, including any `type:` the CLI
+writes in, the body, and bundled files' paths and sizes — and answers
+`{status, type, tier, capabilities, asset_count, flags, warnings, note}`
+with `status` `dry_run_passed` (exit 0) or `dry_run_failed` (exit 30).
+A pass can still list `flags` that do not block. `warnings` come from a
+local scan for content that looks private — `ipv4_or_internal_host`,
+`credential_like_string`, `absolute_home_path`,
+`first_person_context_hint` — and never block.
+
+It decides nothing the registry decides: no name conflict, no version (a
+frontmatter `version` is not checked against the bump), no lineage
+source, no declared-capability check, no rate limit, and no AI review.
+Apart from finishing a pending `kordis login --emit-only`, as every
+command does, its one registry call is a package lookup for
+`--bump minor` or `--bump major` (0.9.1+), made when it can tell which
+package: the frontmatter has a `name`, and you are signed in or `--slug`
+names `<user>/<slug>`. A bump on a package that does not exist yet is
+refused — `usage_error`, exit 2, from 0.9.2 (0.9.1 exits 1) — and if the
+lookup fails any other way, the check is skipped. Only a real push gets
+the registry's verdicts, including the AI review, which can land
+`passed` / `rejected`, or leave the publish `status: "pending"` if the
+worker hasn't decided within the wait window.
+
+**Success criteria**: `status: "dry_run_passed"`.
+
+### 2. Resolve what comes back
+
+From the dry run:
+
+- `dry_run_failed` (exit 30) — fix every listed flag, dry-run again.
+- `usage_error` (exit 2) — a `--type` the frontmatter contradicts, or
+  `--bump minor` / `major` on a first publish; the message says which.
+- `generic_failure` (exit 1) with a YAML hint — the frontmatter does not
+  parse; fix it as the hint says.
+- `generic_failure` (exit 1) — the path is not a package the CLI can read:
+  it does not exist, a folder has no SKILL.md at its top, or a `.skill`
+  archive is broken or has no SKILL.md; the message says which.
+
+Only from the real push (step 3), however clean the dry run was:
+
+- `validation_failed` (exit 30) — the registry's checks: the dry run's,
+  plus ones it does not make, such as a `hook` or `mcp-server` that
+  declares `executable: false`; fix every listed flag.
+- `usage_error` (exit 2) — for example a lineage source that does not
+  resolve, or a frontmatter `version` the bump does not produce; the
+  message says which. Nothing is written.
 - `conflict` (exit 40) — slug taken; suggest a different slug (or pass
   `--slug` if first publish).
-- `ai_review_rejected` (exit 32) — EXPLAIN the rejection to the user. Do NOT
-  silently retry. Includes deterministic Stage-1 hits like
-  `curl_pipe_shell`, `aws_access_key`, `private_key_block`, etc.
+- Review rejection — not an error: the push exits 0 and returns
+  `status: "rejected"` with the reasons in `review.flags`
+  (`ai_review_rejected`, exit 32, is defined but never sent). EXPLAIN the
+  rejection to the user. Do NOT silently retry. Includes deterministic
+  Stage-1 hits like `curl_pipe_shell`, `aws_access_key`,
+  `private_key_block`, etc.
 - `rate_limited` (exit 31) — wait `retry_after_seconds`.
 - `not_authenticated` (exit 10) — `kordis login`, then retry.
 
-**Success criteria**: dry-run is clean.
+**Success criteria**: the dry run passed.
 
 ### 3. Real push
 
@@ -212,9 +278,10 @@ yet — re-check with `kordis info <full_slug> --json` (or wait and re-run
 ## Versioning your push (0.9.0+)
 
 - **First publish** derives the version from the frontmatter `version:`
-  field if present, else defaults to `0.1.0`. Passing `--bump` on a
-  first publish now returns a clear `usage_error` (pre-0.9 silently
-  ignored it) — drop `--bump` or set the frontmatter version explicitly.
+  field if present, else defaults to `0.1.0`. Passing `--bump minor` or
+  `--bump major` on a first publish now returns a clear `usage_error`
+  (pre-0.9 silently ignored it); `--bump patch`, the default, is ignored
+  there — drop `--bump` or set the frontmatter version explicitly.
 - **Subsequent pushes** default to `--bump patch`. Explicit
   `--bump minor` or `--bump major` ships the matching jump.
 - **Frontmatter `version:` on an update** must match the result of
@@ -242,19 +309,21 @@ silently retry — explain why.
 User (push-back after adapting a judgment): "that decision rule we adapted from
 <upstream/slug> worked well — share our version back"
 1. author the refitted judgment as a judgment-pattern file (structured
-   frontmatter; see "Publishing a judgment-pattern")
+   frontmatter with `type: judgment-pattern`, which the `--type` below
+   must match; see "Publishing a judgment-pattern")
 2. kordis push ./judgment.md --type judgment-pattern --adapted-from <upstream/slug> --dry-run --json
 3. clean → drop --dry-run for the real push
-4. the response's `lineage.recorded` confirms the edge; if `lineage.skipped`
-   lists the source, the upstream slug was wrong or unpublished — fix it, or
-   publish the source first, then re-push. The edge gives the upstream
+4. the response's `lineage.recorded` confirms the edge. A wrong or unpublished
+   upstream slug is refused here, by the real push, with `usage_error` and
+   nothing written — the dry run in step 2 does not look sources up. Fix the
+   slug, or publish the source first. The edge gives the upstream
    `community-adapted` credit and shows in its "Adapted by" graph.
 </example>
 
 <example>
 User: "publish my new skill"
 1. kordis push ./SKILL.md --dry-run --json
-2. validation_failed → list each flag, fix the file, re-run
+2. dry_run_failed → list each flag, fix the file, re-run
 3. clean → kordis push ./SKILL.md --json
 4. show {full_slug, version, url}
 </example>
@@ -264,7 +333,8 @@ User: "release v0.2.0 of <full_slug>"
 - previous version was 0.1.x
 1. drop or align the frontmatter `version` field — `--bump minor` from
    0.1.x will yield 0.2.0; if the file says `0.2.0` that matches and is OK,
-   if it says anything else (e.g. `0.1.0`) the API will reject
+   if it says anything else (e.g. `0.1.0`) the real push is refused (the
+   dry run does not compare versions)
 2. kordis push <file> --bump minor --dry-run --json
 3. clean → kordis push <file> --bump minor --json
 </example>

package/assets/kordis-recommend/SKILL.md

@@ -46,7 +46,8 @@ Anonymous: works without login. Personalized signal rides on an opt-in
 `X-Kordis-Context` HTTP header (installed agent tools, top 3 CWD file
 extensions, framework hints from package.json/pyproject.toml/Cargo.toml,
 SHA-256-truncated hashes of installed slugs). Server uses it for in-flight
-re-ranking ONLY — never persisted (see CLAUDE.md "Telemetry / privacy").
+re-ranking ONLY — never persisted (see `docs/security.md` in the Kordis
+repository, "Search, context and addresses").
 
 ## Personalization opt-in
 

package/assets/kordis-social/SKILL.md

@@ -51,6 +51,23 @@ Post a top-level comment on a package. Auth required.
 - `question` — explicit question expecting a reply (typically from the
   author). Use when the user wants a response, not just to share thought.
 
+**What the server refuses.** A comment's title and body get the same content
+screen a published package gets: a download piped into a shell, an encoded
+`eval`, API keys, tokens and private keys, and acceptable-use violations
+(markets for stolen data, malware or attacks for hire, drug and weapon
+brokering, abuse material, targeted harassment). A hit refuses the whole
+comment with `usage_error` (exit 2) and nothing is posted, so there is nothing
+to delete. The message names the field that matched (`comment title rejected …`
+or `comment body rejected …`). Rewrite that field as the hint says and run the
+command again; never resend the same text.
+
+- **Reports: describe, do not quote.** A `report` that pastes the offending
+  line of a dangerous package (a `curl … | bash`, a key) is refused by the
+  same screen. Say what the step does and where it is instead.
+- **Marker lines come back `[redacted]`.** A title or body line that imitates
+  the registry's untrusted-content markers is stored as `[redacted]`. Show the
+  user the `title` the response returns, not the one you sent.
+
 Replies, edits, status flips (open/resolved on a `report`), listing
 existing comments, and reading back your own comments are NOT yet exposed
 in the CLI. Direct the user to `https://kordis.store/<full_slug>` for
@@ -140,6 +157,8 @@ User: "leave a tip on foo/bar saying it pairs well with baz/qux"
 User: "report that the v0.3.0 release of foo/bar is broken on macOS"
 - kordis comment foo/bar --kind report --title "v0.3.0 broken on macOS" \
     --body "<reproducible details>" --json
+- if it is refused (`usage_error`, exit 2), describe the problem without
+  quoting the offending text and post again
 - mention that opening/resolving the report later requires the web UI
 </example>
 

package/assets/kordis-using/SKILL.md

@@ -56,7 +56,13 @@ Returns the full body (Markdown) of a text-bearing package, plus an
 `attribution` string. `--pin <semver>` overrides any `@suffix` on the slug.
 **Context economy**: `--outline` returns just the section map (heading names);
 then `--section <name>` returns one section's body. Read the outline first
-when a body is large and you only need part of it.
+when a body is large and you only need part of it. A section name the package
+does not have exits 2 (`usage_error`): under `--json` the refusal is the error
+envelope on stdout, and its `hint` lists the section names that do exist (or,
+for a package with none, says to read the whole body); without `--json` it goes
+to stderr only, so a body redirected into a file never captures it. Either way,
+the `kordis read` command it prints keeps the version, `--pin` and
+`--allow-pending` you read with, so it reaches the same body.
 
 **Untrusted-content fence (all output modes, incl. `--json`)**: the body (and
 outline description / section slice) arrives wrapped between exactly two lines

package/assets/memgineering-recall/SKILL.md

@@ -153,6 +153,11 @@ What you must not do is report what came back as everything the brain holds,
 which is exactly what a short answer looks like to anyone who does not read the
 line under it.
 
+When every card with a project came from ONE project and the brain holds
+others, recall says so (`scope_spread`: the project, and up to five others). If
+the user meant one of those, ask again with `--scope <that project>` — the note
+they want may be ranked just below a page full of the one the question named.
+
 ## Whether meaning was searched
 
 A hosted brain can match on meaning as well as words — the same idea in other
@@ -177,28 +182,91 @@ anything about what the user knows.
 If coverage says notes are missing entries, meaning was searched over part of
 the brain. Do not report that as a complete search.
 
+When meaning was used, each card also says what reached it — `matched`:
+`"words"`, `"meaning"`, or `"both"`. A `"meaning"` card (printed as _matched by
+meaning only_) shares no word with the question. That is right for a note in
+another language and wrong for one the model merely found nearby, so read its
+summary before you answer from it — never quote it back on the label alone.
+
 ## Two answers that are answers
 
 **Nothing matched.** Say so, and do not go read their folder yourself to
-compensate. At the default depth this has already searched every note body of
-**the brain it searched**, so "nothing" is real information about that brain
-rather than a hint to search harder — read `semantic` first, per above. Broader
-words are still worth one retry; `--depth exact` is not — it looks at strictly
-less.
+compensate. At the default depth this has already searched the body of every
+note recall could read in **the brain it searched**, so "nothing" is real
+information about those notes rather than a hint to search harder — read
+`semantic` first, per above. Broader words are still worth one retry;
+`--depth exact` is not — it looks at strictly less.
+
+In a brain in a folder, that is not a promise about every file. Notes it left
+out are counted below, but recall never looks inside a folder the user's own
+rules exclude (`.gitignore`, `.memgignore`, the rules file): notes in one are
+neither searched nor counted, and an answer where other notes were searched does
+not mention them. So an empty answer is not proof that the user never wrote
+something down. Say what was searched, and that folders their rules exclude
+were not, rather than telling them they never wrote it. Do not open such a
+folder yourself.
 
 One brain is not the account. On a hosted account with more than one brain, an
-empty answer now names the brains that were NOT read and prints a runnable
-`--brain` command for each. Run it before you tell them the fact was never
-written down — four testers reached that conclusion about a note sitting in the
-next brain, and three of them said it out loud. Reading another brain does not
-move the machine's pointer.
+empty answer — or one of template cards only — names the brains that were NOT
+read and prints a runnable `--brain` command for each. Run it before you tell
+them the fact was never written down — four testers reached that conclusion
+about a note sitting in the next brain, and three of them said it out loud.
+Reading another brain does not move the machine's pointer.
+
+With `--json`, an answer with nothing the user wrote in it carries `hint`: no
+cards, or only template cards (`scaffolding: true`, below) — those are what
+`init` wrote, not the user's notes. `hint` is the one next step, the most
+specific that applies. First, the brain had nothing to search: it has no notes
+yet (the `remember` command that writes the first one into that brain — or,
+after `--brain` named a brain this machine does not point at, the
+`memgineering use --brain "<name>"` that makes it the target, since `remember`
+has no `--brain`), or it is a folder whose every note was left out (how many,
+why, and the `memgineering reindex` command that names each one). Then: its
+notes are in a script the question is not (ask again in that language), another
+brain was not read (the `--brain` or `--vault` command that reads it), meaning
+was not searched (and the server's reason), the hosted server's own advice, or
+fewer and broader words. Read it before you conclude anything from
+`cards: []` or from template cards. A `memgineering use --brain` in a hint
+moves this machine's pointer for every later command, not just the next one:
+offer it to the user and run it only on their yes. `hint` is absent whenever a
+card they wrote came back.
+
+**Held-back notes are counted in both modes.** When an answer has nothing the
+user wrote in it, recall counts what a brain in a folder left out, says why,
+and prints the `memgineering reindex` command that names each one: in the
+terminal right under `_Nothing matched._` or under the template cards' header,
+and at the front of `hint`. It opens with "Nothing in this brain could be
+searched: …" when no note could be searched at all, and with "Not every note in
+this brain was searched: …" when other notes were searched and at least one
+note of the first kind below was left out. Recall itself never names or shows a
+left-out note. The counts come in two kinds, and they mean different things:
+
+- **Notes**: excluded by the user's rules (`.gitignore`, `.memgignore`, the
+  rules file), listed in `.memgdeny`, held back because the name looks private,
+  refused because the content looks like a credential, or behind a symlink. A
+  note the user wrote exists and was left out on purpose. Do NOT tell them the
+  brain is empty or that they never wrote it down: tell them such a note exists,
+  and why; to say where it is, run that `reindex` — it lists each path and
+  changes no note — and give them the path. Do not open, print or read a
+  held-back note into the conversation unless they ask what it says: it was
+  held back because it may be private.
+- **Places nobody looked inside**: an excluded folder ("not looked inside"), or
+  another symlink, which is never followed. These are not evidence of a note —
+  an ignored `images/` or `.venv/` holds none. Say that recall could not look
+  inside them and that `reindex` names them; do not say a note was held back.
+  When "Nothing in this brain could be searched" lists only these, the brain may
+  hold no notes at all. Beside notes that were searched they are not counted at
+  all — see **Nothing matched** above.
 
 **Cards that are not answers.** A card marked `not filled in yet` is one of the
-five `01_BASE/` files, still byte-for-byte what `init` wrote. Nobody has answered
+five `01_BASE/` files, still exactly what `init` wrote (line endings aside). Nobody has answered
 it, so it is evidence of nothing — do not quote it back as what they think. When
 every card carries that mark, recall says so above them (`--json`:
 `scaffolding: true`), and that is the moment to offer to fill them in rather
-than answer from them — see `memgineering-writing`.
+than answer from them — see `memgineering-writing`. At most two such cards come
+back per answer, plus any that is one side of a conflict, so both sides of a
+conflict always show; the rest are counted (`templates_withheld`), never
+silently dropped, and nothing anyone wrote is ever held back.
 
 The mark disappears once the user writes in the file. A filled-in base note is
 often the best answer in the brain: _who am I_, _what am I not allowed to do_,
@@ -219,8 +287,11 @@ On a hosted brain the folder counts too, as a name rather than a path: the CLI
 sends the folder's project — `owner/repo` from the git remote, or whatever
 `memgineering project` shows — and the server ranks what was asked about in
 that project first. The response says so itself: `ranked_by` gains `asked about
-in this project`, a card's reason reads `recalled 2× in this project`, and the
-footer names which project those words mean. Trust the footer over your
+in this project`, a card's reason reads `opened 1× · surfaced 2× in this project`
+(or `surfaced 2× …, never opened`), and the footer names which project those
+words mean. Only an open, or being the FIRST card of a recall, counts toward
+the order; a card merely listed further down is counted in words but earns
+nothing. Trust the footer over your
 assumption in the other cases as well — it says when this folder names no
 project (nothing was sent), and when the server does not rank by project yet
 (it was sent and ignored). A path never leaves the machine either way.