@rayul/kordis 0.15.2 → 0.16.0

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.26.0
+version: 0.27.0
 ---
 
 # memgineering

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                                         |
 | ----------------------- | ------------ | ----------------------------------------------- |
@@ -82,10 +112,10 @@ feeds the `community-adapted` trust tier, and gives a small trending boost:
 
 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 `--dry-run` refuses it the same way, so a dry run
-catches a typo before anything is written. 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
+`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+)
@@ -163,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")               |
@@ -174,29 +204,58 @@ 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).
-- Review rejection — never from a dry-run, which does not run the reviewer.
-  On the real push (step 3) a rejection is not an error: the push exits 0
-  and returns `status: "rejected"` with the reasons in `review.flags`
+- 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`,
@@ -204,7 +263,7 @@ Possible verdicts:
 - `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
 
@@ -219,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
@@ -249,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. A wrong or unpublished
-   upstream slug never gets this far: step 2's dry run already refuses it with
-   `usage_error` — fix the slug, or publish the source first. The edge gives the
-   upstream `community-adapted` credit and shows in its "Adapted by" graph.
+   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>
@@ -271,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-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

@@ -191,18 +191,72 @@ 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 exactly what `init` wrote (line endings aside). Nobody has answered

package/assets/memgineering-setup/SKILL.md

@@ -506,17 +506,23 @@ by hand in the ordinary case — writes keep the index in step on their own.
 what is missing and clears stored rows for notes the brain has since been told
 not to read, reporting both; `--local` forces the folder brain. On a brain in a
 FOLDER it also names what it left out — notes a deny name, a `.memgignore` rule
-or a symlink kept from the index, and any folder a rule excluded whole — so "3
-notes rebuilt" is never the whole answer when a fourth was dropped. A hosted
-reindex cannot say that: the rules are applied on the machine that pushed, so
-the server only ever saw what arrived.
+or a symlink kept from the index, any folder a rule excluded whole, and any other
+symlink, which is never followed — so "3 notes rebuilt" is never the whole
+answer when a fourth was dropped. A hosted reindex cannot say that: the rules are
+applied on the machine that pushed, so the server only ever saw what arrived.
 
 Under `--json` that is `not_indexed` with `denied_by_name`, `denied_explicitly`,
-`excluded_by_rule`, `skipped_symlinks` and `excluded_folders`. **Read the count
-together with `excluded_folders`**: a rule that names a folder stops the walk at
-the folder, so nothing inside it is ever counted — `not_indexed: 0` beside a
-non-empty `excluded_folders` means the count is a floor, not the answer. `push`
-reports the same set with its total under `not_sent`. `--rebuild`
+`excluded_by_rule`, `skipped_symlinks`, `excluded_folders` and
+`skipped_other_symlinks`. **Read the count together with the last two**: a rule
+that names a folder stops the walk at the folder, and a symlink is never
+followed, so the notes in such a folder are never counted — `not_indexed: 0`
+beside a non-empty `excluded_folders` or `skipped_other_symlinks` means the count
+is a floor, not the answer. `push` reports the same set with its total under
+`not_sent`. A `recall` that brings back nothing the user wrote — no cards, or
+only templates — counts the same set by reason in both modes (beside notes it
+did search, only when a note is among them) and prints this command, never a
+path; what to tell the user then is in `memgineering-recall`.
+`--rebuild`
 exists for one situation only, where an embedding model changed the shape of its
 answers without changing its name and the index has to be laid down again.
 

package/dist/index.js

@@ -134,12 +134,32 @@ var init_enums = __esm({
   }
 });
 
+// ../../packages/contracts/src/refresh-race.ts
+function isRefreshRace(body) {
+  if (typeof body !== "object" || body === null) return false;
+  const error = body.error;
+  if (typeof error !== "object" || error === null) return false;
+  const { code, flags } = error;
+  if (code !== "not_authenticated" || !Array.isArray(flags)) return false;
+  return flags.some(
+    (flag2) => typeof flag2 === "object" && flag2 !== null && flag2.code === REFRESH_RACE_FLAG
+  );
+}
+var REFRESH_RACE_FLAG;
+var init_refresh_race = __esm({
+  "../../packages/contracts/src/refresh-race.ts"() {
+    "use strict";
+    REFRESH_RACE_FLAG = "refresh_rotated_by_another_request";
+  }
+});
+
 // ../../packages/contracts/src/errors.ts
 import { z as z3 } from "zod";
 var ErrorCodeSchema, ERROR_EXIT_CODES, ReviewFlagSchema, ApiErrorSchema;
 var init_errors = __esm({
   "../../packages/contracts/src/errors.ts"() {
     "use strict";
+    init_refresh_race();
     ErrorCodeSchema = z3.enum([
       "generic_failure",
       // 1
@@ -1159,21 +1179,33 @@ var init_api = __esm({
        */
       content: z11.string().min(50).max(1e5),
       /**
-       * Accepted and ignored. core-api stores the title, description and type it
-       * reads from the frontmatter of `content`, which must carry all three; these
-       * three fields change nothing (`kordis push --type` sends `type` here).
+       * Optional, and refused when it disagrees. core-api stores the title,
+       * description and type it reads from the frontmatter of `content`, which must
+       * carry all three (the title may come from `name:`). A value here that
+       * differs from the frontmatter's, compared trimmed, is refused as
+       * `usage_error` (HTTP 400) with a hint naming the frontmatter key; absent
+       * means no claim. A `type` the registry cannot publish at all (`scoped-rule`,
+       * `mdc-rule`, `plugin`) names no key to write: its hint says the type cannot
+       * be published yet and to drop `--type`. `kordis push` ≤0.15.2 sends
+       * `--type` here, and writes `type: skill` into the frontmatter of a SKILL.md
+       * or *.skill.md file, a folder or a .skill bundle that names no type — so
+       * `--type hook` on one is refused, where until 2026-10 it published a skill.
+       * Later versions send no `type`: they write `--type` into the frontmatter.
        */
       title: z11.string().min(1).max(200).optional(),
       description: z11.string().min(1).max(2048).optional(),
       type: HarnessTypeSchema.optional(),
       /**
        * A new package is published under this slug instead of the one derived from
-       * the frontmatter title. An update keeps the slug of the package it updates.
+       * the frontmatter title. An update keeps the slug of the package it updates:
+       * a slug here that differs from the target's is refused (`usage_error`).
        */
       slug: SlugSchema.optional(),
       /**
-       * When updating, the target full_slug. Omitted for new packages (server
-       * derives slug from title or accepts inline `slug`).
+       * When updating, the target full_slug; its presence is what makes a publish
+       * an update (`PUT /api/packages/:u/:s` sets it from the path). Omitted for a
+       * new package, whose slug is `slug` or else derived from the frontmatter
+       * title — never derived on an update.
        */
       target_full_slug: FullSlugSchema.optional(),
       /**
@@ -1181,6 +1213,12 @@ var init_api = __esm({
        */
       bump: z11.enum(["patch", "minor", "major"]).optional(),
       changelog: z11.string().max(2e3).optional(),
+      /**
+       * Refused when non-empty (`usage_error`): a package's dependencies are read
+       * from its frontmatter's `depends:` and `recommends:` lists only. Kept in the
+       * schema so the server sees them to refuse them — this object is non-strict,
+       * and an unlisted key would be stripped without a word.
+       */
       depends: z11.array(z11.string()).optional(),
       recommends: z11.array(z11.string()).optional(),
       /**
@@ -1680,9 +1718,122 @@ var init_telemetry = __esm({
 });
 
 // ../../packages/contracts/src/review-patterns.ts
+var STAGE_1_REJECT_PATTERNS, STAGE_1_5_AUP_PATTERNS, DETERMINISTIC_REJECT_PATTERNS;
 var init_review_patterns = __esm({
   "../../packages/contracts/src/review-patterns.ts"() {
     "use strict";
+    STAGE_1_REJECT_PATTERNS = [
+      {
+        code: "curl_pipe_shell",
+        pattern: /\bcurl\s+[^|;]+\s*\|\s*(?:(?:sudo|doas)\s+)?(?:-E\s+|[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:sh|bash|zsh|ksh|dash|csh|tcsh|fish)\b/i,
+        hint: "Replace `curl \u2026 | bash` with a verifiable install path: download the script to a file, show the user `cat` of it for inspection, then `bash <file>` only after confirmation."
+      },
+      {
+        code: "wget_pipe_shell",
+        pattern: /\bwget\s+[^|;]+\s*\|\s*(?:(?:sudo|doas)\s+)?(?:-E\s+|[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*(?:sh|bash|zsh|ksh|dash|csh|tcsh|fish)\b/i,
+        hint: "Replace `wget \u2026 | bash` with a verifiable install path: download the script to a file, show the user `cat` of it for inspection, then `bash <file>` only after confirmation."
+      },
+      {
+        code: "shell_process_substitution",
+        pattern: /(?:bash|sh|zsh)\s*<\(\s*(?:curl|wget)\b/i,
+        hint: "Replace `bash <(curl \u2026)` with a verifiable install path: download the script to a file, show the user `cat` of it for inspection, then `bash <file>` only after confirmation."
+      },
+      {
+        code: "eval_atob",
+        pattern: /\beval\s*\(\s*atob\b/i,
+        hint: "Encoded eval (`eval(atob(...))`) is a hallmark of obfuscated payloads. Move the logic into plain code the reader can audit."
+      },
+      {
+        code: "eval_buffer_from",
+        pattern: /\beval\s*\(\s*Buffer\.from\b/i,
+        hint: "Encoded eval (`eval(Buffer.from(...))`) is a hallmark of obfuscated payloads. Move the logic into plain code the reader can audit."
+      },
+      {
+        code: "aws_access_key",
+        pattern: /\b(?:AKIA|ASIA|AGPA)[0-9A-Z]{16}\b/,
+        hint: "Remove the AWS access key from the body. Reference credentials via env var (`AWS_ACCESS_KEY_ID`); rotate the leaked key immediately if it was real."
+      },
+      {
+        code: "private_key_block",
+        pattern: /-----BEGIN\s+(?:[A-Z0-9]+\s+)?PRIVATE\s+KEY(?:\s+BLOCK)?-----/,
+        hint: "Remove the private key block from the body. Reference keys via env var or a secret manager; rotate the leaked key immediately if it was real."
+      },
+      {
+        code: "google_api_key",
+        pattern: /\bAIza[0-9A-Za-z_-]{35}\b/,
+        hint: "Remove the Google API key from the body. Reference credentials via env var; rotate the leaked key immediately if it was real."
+      },
+      {
+        code: "slack_token",
+        pattern: /\b(?:xox[abpors]|xapp|xoxe)-[0-9a-zA-Z-]{10,}\b/,
+        hint: "Remove the Slack token from the body. Reference tokens via env var; revoke the leaked token immediately if it was real."
+      },
+      {
+        code: "github_token",
+        pattern: /\b(?:gh[pousr]_[A-Za-z0-9_]{36,}|github_pat_[A-Za-z0-9_]{60,})\b/,
+        hint: "Remove the GitHub token from the body. Reference tokens via env var; revoke the leaked token immediately if it was real."
+      }
+    ];
+    STAGE_1_5_AUP_PATTERNS = [
+      {
+        // Stolen-card / bank-credential trafficking storefronts. Anchored to the
+        // trafficking jargon that only appears in carding markets, not in the
+        // defensive "how to detect carding" literature. `dumps` is also an
+        // ordinary developer verb — "this hook dumps vendor files", "dumps store
+        // state", "dumps market data to CSV" all matched the shared noun list —
+        // so after `dumps` only sale framing (`shop`, `for sale`) counts, while
+        // `cvv` and `fullz` keep the full list. Narrowed when comments started
+        // running this table (2026-10-14).
+        code: "aup_stolen_financial_data_market",
+        pattern: /\b(?:cvv|fullz)\s+(?:shop|store|for\s+sale|market|vendor)\b|\bdumps\s+(?:shop|for\s+sale)\b|\bdumps?\s+with\s+pin\b|\bsell(?:ing)?\s+(?:cvv|fullz|dumps)\b/i,
+        hint: "This reads as a storefront for trafficking stolen financial data, which violates the Kordis AUP. If the package is about DETECTING or DEFENDING against card fraud, reword it so it does not read as an offer to buy/sell stolen data."
+      },
+      {
+        // DDoS-for-hire (booter/stresser) services sold on a subscription.
+        code: "aup_ddos_for_hire",
+        pattern: /\b(?:booter|stresser)\s+(?:service|panel|subscription)\b|\b(?:ddos|dstat)\s+for\s+hire\b|\bhire\s+(?:a\s+)?(?:booter|stresser|ddos)\b/i,
+        hint: "This reads as a DDoS-for-hire (booter/stresser) service, which violates the Kordis AUP. Load-testing tooling is fine \u2014 describe it as testing infrastructure you own/are authorized to test, not a for-hire attack service."
+      },
+      {
+        // Malware/stealer/ransomware sold or distributed as a product ("builder
+        // for sale", "buy our stealer"). A skill that DEFENDS against these, or a
+        // malware-analysis skill, does not use buy/sell framing.
+        code: "aup_malware_sale",
+        pattern: /\b(?:ransomware|stealer|infostealer|rat|keylogger|botnet)\s+(?:builder|kit|panel|source)\s+(?:for\s+sale|for\s+rent)\b|\b(?:buy|sell(?:ing)?|rent)\s+(?:our\s+)?(?:ransomware|stealer|infostealer|botnet)\b/i,
+        hint: "This reads as an offer to sell/rent malware, which violates the Kordis AUP. Malware ANALYSIS and DEFENSE content is welcome \u2014 reword so it does not read as distributing a weaponized build."
+      },
+      {
+        // Child sexual abuse material. Unlike the rest of this table this entry is
+        // NOT anchored to solicitation: it matches the spelled-out phrases ("child
+        // porn", "child pornography", "child sexual abuse material") wherever they
+        // appear, child-safety and moderation education included. Only the
+        // acronym "CSAM" on its own does not match ("how platforms detect CSAM
+        // for NCMEC reporting" passes). Kept this broad on purpose (2026-10-14):
+        // comments have no Stage-2 review after this table, so a miss costs more
+        // than a false positive.
+        code: "aup_csam",
+        pattern: /\bchild\s+(?:porn(?:ography)?|sexual\s+abuse\s+material)\b/i,
+        hint: "This reads as solicitation or distribution of child sexual abuse material, which is illegal and violates the Kordis AUP. This is a terminal, non-appealable rejection."
+      },
+      {
+        // Drug / untraceable-weapon brokering with explicit no-id / untraceable /
+        // dark-web fulfillment language — not a bare mention of a substance or
+        // firearm topic (e.g. harm-reduction or policy content does not use this
+        // buy/sell + untraceable-fulfillment framing together).
+        code: "aup_drug_weapon_brokering",
+        pattern: /\b(?:buy|sell(?:ing)?)\b[\s\S]{0,40}\b(?:cocaine|heroin|fentanyl|methamphetamine|untraceable firearms?|untraceable guns?)\b[\s\S]{0,40}\b(?:no id|untraceable|worldwide shipping|dark ?web)\b/i,
+        hint: "This reads as brokering illegal drugs or untraceable weapons for sale, which violates the Kordis AUP. If the package is about DETECTING or REPORTING such activity, reword it so it does not read as an offer to buy/sell."
+      },
+      {
+        // A directive to dox or swat a specific, named/tagged target — not a
+        // bare mention of doxxing/swatting as a topic (e.g. "how to protect
+        // yourself from doxxing" does not match).
+        code: "aup_targeted_harassment_directive",
+        pattern: /\b(?:dox|swat)\s+(?:this (?:guy|girl|person|user)|him|her|@[\w.]+)\b/i,
+        hint: "This reads as a directive to dox or swat a specific target, which violates the Kordis AUP. Remove the targeted-harassment instruction."
+      }
+    ];
+    DETERMINISTIC_REJECT_PATTERNS = [...STAGE_1_REJECT_PATTERNS, ...STAGE_1_5_AUP_PATTERNS];
   }
 });
 
@@ -7882,13 +8033,18 @@ async function useClient() {
         } catch (err) {
           const code = err.code;
           if (code === "authorization_pending") {
-            if (debug) process.stderr.write("[kordis] auto-finalize: authorization_pending (keeping pending)\n");
+            if (debug)
+              process.stderr.write(
+                "[kordis] auto-finalize: authorization_pending (keeping pending)\n"
+              );
           } else {
             await clearPending();
             if (debug) {
               const msg = err instanceof Error ? err.message : String(err);
-              process.stderr.write(`[kordis] auto-finalize: poll failed (code=${code ?? "none"}): ${msg}
-`);
+              process.stderr.write(
+                `[kordis] auto-finalize: poll failed (code=${code ?? "none"}): ${msg}
+`
+              );
             }
             void reportError("auto_finalize_stage1_fail", err);
           }
@@ -7912,7 +8068,8 @@ async function useClient() {
             cfg = { ...cfg, username, sessionId: pollResult.session_id };
             await saveCliConfig(cfg);
             await clearPending();
-            if (debug) process.stderr.write(`[kordis] auto-finalize: persisted tokens for ${username}
+            if (debug)
+              process.stderr.write(`[kordis] auto-finalize: persisted tokens for ${username}
 `);
           } catch (err) {
             await clearPending();
@@ -7941,31 +8098,51 @@ async function useClient() {
       }
     } : {}
   });
+  const renewTokens = async (user, sent) => {
+    try {
+      const refreshed = await api.refreshSession(sent);
+      currentTokens = {
+        access_token: refreshed.access_token,
+        refresh_token: refreshed.refresh_token,
+        session_id: refreshed.session_id,
+        expires_at_epoch: Math.floor(Date.now() / 1e3) + refreshed.expires_in
+      };
+      await keychain.save(user, currentTokens);
+      await saveCliConfig({ ...cfg, sessionId: refreshed.session_id });
+      return true;
+    } catch (refreshErr) {
+      if (!lostRefreshRace(refreshErr)) return false;
+      const stored = await storedPairOtherThan(user, sent);
+      if (stored === null) return false;
+      currentTokens = stored;
+      return true;
+    }
+  };
   const authedRequest = async (fn) => {
     try {
       return await fn(api);
     } catch (err) {
-      if (err instanceof KordisApiError && err.code === "not_authenticated" && currentTokens && username) {
-        try {
-          const refreshed = await api.refreshSession(currentTokens.refresh_token);
-          currentTokens = {
-            access_token: refreshed.access_token,
-            refresh_token: refreshed.refresh_token,
-            session_id: refreshed.session_id,
-            expires_at_epoch: Math.floor(Date.now() / 1e3) + refreshed.expires_in
-          };
-          await keychain.save(username, currentTokens);
-          await saveCliConfig({ ...cfg, sessionId: refreshed.session_id });
-          return await fn(api);
-        } catch {
-          throw err;
-        }
-      }
-      throw err;
+      const renewed = err instanceof KordisApiError && err.code === "not_authenticated" && currentTokens !== null && username !== null && await renewTokens(username, currentTokens.refresh_token);
+      if (!renewed) throw err;
     }
+    return fn(api);
   };
   return { api, keychain, username, apiUrl: cfg.apiUrl, authedRequest };
 }
+function lostRefreshRace(err) {
+  return err instanceof KordisApiError && err.status === 401 && isRefreshRace({ error: { code: err.code, flags: err.flags } });
+}
+var RACE_REREADS_AT_MS = [500, 1e3, 2e3];
+async function storedPairOtherThan(username, sent) {
+  let waited = 0;
+  for (const at of RACE_REREADS_AT_MS) {
+    await new Promise((resolve6) => setTimeout(resolve6, at - waited));
+    waited = at;
+    const stored = await createKeychain().then((store) => store.load(username)).catch(() => null);
+    if (stored !== null && stored.refresh_token !== sent) return stored;
+  }
+  return null;
+}
 
 // src/ui.ts
 import kleur from "kleur";
@@ -9287,6 +9464,7 @@ function lintForLeaks(sources) {
 }
 
 // src/commands/push.ts
+init_src();
 var collect = (val, acc) => acc.concat(val);
 function toLineage(raws, kind) {
   return (raws ?? []).map((raw) => {
@@ -9301,7 +9479,10 @@ function toLineage(raws, kind) {
 var ASSET_MAX_BYTES = 2 * 1024 * 1024;
 var BUNDLE_MAX_BYTES = 5 * 1024 * 1024;
 function pushCommand() {
-  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option("--slug <slug>", 'override slug; accepts "user/slug" to point at a specific package').option("--type <type>", "override type inference").option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").option(
+  return new Command4("push").description("publish a new package or a new version").argument("<path>", "SKILL.md file, .skill ZIP, or skill directory").option("--bump <strategy>", "patch|minor|major (update only)", "patch").option("--slug <slug>", 'override slug; accepts "user/slug" to point at a specific package').option(
+    "--type <type>",
+    "type to write into a frontmatter that names none (else a SKILL.md, folder or .skill is a skill); refused if the frontmatter names another"
+  ).option("--changelog <text>", "optional changelog entry").option("--dry-run", "validate only; do not publish").option("--no-wait", "return immediately without waiting for review").option(
     "--adapted-from <slug>",
     "source this package was adapted from (repeatable); records lineage",
     collect,
@@ -9316,17 +9497,15 @@ function pushCommand() {
       let contentLabel = "SKILL.md";
       if (s.isDirectory()) {
         ({ content, assets } = await bundleDirectory(abs));
-        content = ensureTypeField(content, "skill");
+        content = resolveType(content, opts.type, "skill");
       } else if (abs.endsWith(".skill")) {
         ({ content, assets } = await bundleSkillZip(abs));
-        content = ensureTypeField(content, "skill");
+        content = resolveType(content, opts.type, "skill");
       } else {
         content = await readFile6(abs, "utf8");
         contentLabel = basename(abs);
         const isSkillFilename = abs.endsWith("/SKILL.md") || abs.endsWith(".skill.md");
-        if (isSkillFilename) {
-          content = ensureTypeField(content, "skill");
-        }
+        content = resolveType(content, opts.type, isSkillFilename ? "skill" : void 0);
       }
       let nameFromFm = null;
       try {
@@ -9406,7 +9585,6 @@ function pushCommand() {
             bump: opts.bump,
             slug: opts.slug && !opts.slug.includes("/") ? opts.slug : void 0,
             target_full_slug: targetFullSlug,
-            type: opts.type,
             changelog: opts.changelog,
             lineage: lineage.length > 0 ? lineage : void 0,
             dry_run: !!opts.dryRun
@@ -9542,15 +9720,39 @@ function printLeakWarnings(findings) {
     printHuman(c.yellow(`    - ${f.message}`));
   }
 }
-function ensureTypeField(content, defaultType) {
+function resolveType(content, typeFlag, inferred) {
+  if (typeFlag === void 0) return inferred ? ensureTypeField(content, inferred) : content;
+  const declared = frontmatterType(content);
+  if (declared === void 0) return ensureTypeField(content, typeFlag);
+  if (declared !== typeFlag) {
+    throw new KordisApiError(400, {
+      error: {
+        code: "usage_error",
+        message: `--type "${typeFlag}" disagrees with the type in the frontmatter, "${declared}"`,
+        hint: `This file's frontmatter says \`type: ${declared}\`; change it or drop \`--type\`.`
+      }
+    });
+  }
+  return content;
+}
+function frontmatterType(content) {
+  try {
+    const value = parseFrontmatter(content).frontmatter?.["type"];
+    return typeof value === "string" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function ensureTypeField(content, type) {
   const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
   if (!fmMatch) return content;
   const fmBlock = fmMatch[1];
   if (/^type\s*:/m.test(fmBlock)) return content;
-  const injected = fmMatch[0].replace(/^---\r?\n/, `---
-type: ${defaultType}
+  const scalar = HarnessTypeSchema.safeParse(type).success ? type : JSON.stringify(type);
+  const injected = fmMatch[0].replace(/^---\r?\n/, () => `---
+type: ${scalar}
 `);
-  return content.replace(fmMatch[0], injected);
+  return content.replace(fmMatch[0], () => injected);
 }
 var EXCLUDE_NAMES = /* @__PURE__ */ new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
 var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["__pycache__", "node_modules", ".git", "evals", "dist", ".turbo"]);
@@ -10226,45 +10428,31 @@ function getTranslator(type, format) {
   return fn;
 }
 
-// src/lockfile.ts
-init_brand();
-import { join as join9 } from "path";
-import { readFile as readFile7, writeFile as writeFile5, mkdir as mkdir5 } from "fs/promises";
-function kordisHome2() {
-  return brandHome();
-}
-function lockfilePath() {
-  return join9(kordisHome2(), "installed.json");
-}
-function lockfileDisplayPath() {
-  const path2 = lockfilePath();
-  const home = process.env["HOME"];
-  return home && path2.startsWith(home) ? "~" + path2.slice(home.length) : path2;
-}
-async function readLockfile() {
-  try {
-    const raw = await readFile7(lockfilePath(), "utf8");
-    return JSON.parse(raw);
-  } catch {
-    return { packages: {} };
-  }
-}
-async function writeLockfile(lf) {
-  await mkdir5(kordisHome2(), { recursive: true });
-  await writeFile5(lockfilePath(), JSON.stringify(lf, null, 2) + "\n", {
-    encoding: "utf8",
-    mode: 384
-  });
-}
-async function recordInstalled(fullSlug, entry) {
-  const lf = await readLockfile();
-  lf.packages[fullSlug] = entry;
-  await writeLockfile(lf);
-}
-
-// src/lib/merge-emitted-file.ts
+// ../../packages/translators/src/merge-emitted-file.ts
 import tomlLib2 from "@iarna/toml";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+var MergeRefusal = class extends Error {
+  code;
+  reason;
+  constructor(reason) {
+    super(refusalMessage(reason));
+    this.name = "MergeRefusal";
+    this.code = reason.kind === "prototype_key" ? "unsafe_package_config" : "merge_refused";
+    this.reason = reason;
+  }
+};
+function refusalMessage(reason) {
+  switch (reason.kind) {
+    case "prototype_key":
+      return `refusing to merge config fragment \u2014 prototype-polluting key "${reason.key}" at ${reason.path}`;
+    case "malformed_file":
+      return `refusing to merge into "${reason.targetPath}" \u2014 existing file is not valid ${reason.format.toUpperCase()}: ${reason.parseError}`;
+    case "non_object_root":
+      return `refusing to merge into "${reason.targetPath}" \u2014 existing ${reason.format.toUpperCase()} root is not an object`;
+    case "dangling_marker":
+      return `refusing to merge \u2014 found a "kordis:${reason.fullSlug}" start marker with no matching end marker`;
+  }
+}
 function isPlainObject(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -10289,11 +10477,7 @@ function assertNoProtoKeys(value, path2) {
   if (!isPlainObject(value)) return;
   for (const [k, v] of Object.entries(value)) {
     if (PROTO_KEYS.has(k)) {
-      const e = new Error(
-        `refusing to merge config fragment \u2014 prototype-polluting key "${k}" at ${[...path2, k].join(".")}`
-      );
-      e.hint = "The package emits a config key named __proto__/constructor/prototype, which no legitimate tool config needs. Report it to the author if you did not publish it.";
-      throw e;
+      throw new MergeRefusal({ kind: "prototype_key", key: k, path: [...path2, k].join(".") });
     }
     assertNoProtoKeys(v, [...path2, k]);
   }
@@ -10302,19 +10486,15 @@ function isOwnedServerLeaf(path2) {
   return path2.length === 2 && (path2[0] === "mcpServers" || path2[0] === "mcp_servers");
 }
 function deepMergeFragment(existing, fragment, path2 = []) {
-  if (path2.length === 0) assertNoProtoKeys(fragment, []);
+  assertNoProtoKeys(fragment, path2);
+  return mergeAt(existing, fragment, path2);
+}
+function mergeAt(existing, fragment, path2) {
   if (isOwnedServerLeaf(path2)) return fragment;
   if (isPlainObject(existing) && isPlainObject(fragment)) {
     const out = { ...existing };
     for (const [k, v] of Object.entries(fragment)) {
-      if (PROTO_KEYS.has(k)) {
-        const e = new Error(
-          `refusing to merge config fragment \u2014 prototype-polluting key "${k}" at ${[...path2, k].join(".")}`
-        );
-        e.hint = "The package emits a config key named __proto__/constructor/prototype, which no legitimate tool config needs. Report it to the author if you did not publish it.";
-        throw e;
-      }
-      out[k] = deepMergeFragment(existing[k], v, [...path2, k]);
+      out[k] = mergeAt(existing[k], v, [...path2, k]);
     }
     return out;
   }
@@ -10357,18 +10537,15 @@ function mergeStructuredFile(existingRaw, fragmentRaw, format, targetPath) {
   try {
     existing = parseStructured(existingRaw, format);
   } catch (err) {
-    const e = new Error(
-      `refusing to merge into "${targetPath}" \u2014 existing file is not valid ${format.toUpperCase()}: ${err.message}`
-    );
-    e.hint = `Fix or remove the malformed ${targetPath}, then re-run \`kordis pull\`/\`kordis update\`. Refusing to overwrite it blind \u2014 it may hold config from other tools/packages.`;
-    throw e;
+    throw new MergeRefusal({
+      kind: "malformed_file",
+      targetPath,
+      format,
+      parseError: err.message
+    });
   }
   if (!isPlainObject(existing) && isPlainObject(fragment)) {
-    const e = new Error(
-      `refusing to merge into "${targetPath}" \u2014 existing ${format.toUpperCase()} root is not an object`
-    );
-    e.hint = `${targetPath} parses but its top level is not an object, so a config fragment can't be merged in. Move the file aside (or fix its shape), then re-run \`kordis pull\`/\`kordis update\`.`;
-    throw e;
+    throw new MergeRefusal({ kind: "non_object_root", targetPath, format });
   }
   const merged = deepMergeFragment(existing, fragment);
   return stringifyStructured(merged, format);
@@ -10390,15 +10567,67 @@ function mergeFencedFile(existingRaw, fullSlug, block) {
     return existingRaw.slice(0, startMatch.index) + trimmedBlock + existingRaw.slice(spanEnd);
   }
   if (startMatch && endIdx === -1) {
-    const e = new Error(
-      `refusing to merge \u2014 found a "kordis:${fullSlug}" start marker with no matching end marker`
-    );
-    e.hint = `The file has a dangling <!-- kordis:${fullSlug}:...:start --> marker. Delete that line (or restore its <!-- kordis:${fullSlug}:end --> line), then re-run \`kordis pull\`/\`kordis update\`.`;
-    throw e;
+    throw new MergeRefusal({ kind: "dangling_marker", fullSlug });
   }
   return existingRaw.trimEnd() + "\n\n" + trimmedBlock + "\n";
 }
 
+// src/lockfile.ts
+init_brand();
+import { join as join9 } from "path";
+import { readFile as readFile7, writeFile as writeFile5, mkdir as mkdir5 } from "fs/promises";
+function kordisHome2() {
+  return brandHome();
+}
+function lockfilePath() {
+  return join9(kordisHome2(), "installed.json");
+}
+function lockfileDisplayPath() {
+  const path2 = lockfilePath();
+  const home = process.env["HOME"];
+  return home && path2.startsWith(home) ? "~" + path2.slice(home.length) : path2;
+}
+async function readLockfile() {
+  try {
+    const raw = await readFile7(lockfilePath(), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return { packages: {} };
+  }
+}
+async function writeLockfile(lf) {
+  await mkdir5(kordisHome2(), { recursive: true });
+  await writeFile5(lockfilePath(), JSON.stringify(lf, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 384
+  });
+}
+async function recordInstalled(fullSlug, entry) {
+  const lf = await readLockfile();
+  lf.packages[fullSlug] = entry;
+  await writeLockfile(lf);
+}
+
+// src/lib/merge-refusal.ts
+function adaptMergeRefusal(err) {
+  if (!(err instanceof MergeRefusal)) return null;
+  const e = new Error(err.message);
+  e.hint = mergeRefusalHint(err.reason);
+  return e;
+}
+function mergeRefusalHint(reason) {
+  switch (reason.kind) {
+    case "prototype_key":
+      return "The package emits a config key named __proto__/constructor/prototype, which no legitimate tool config needs. Report it to the author if you did not publish it.";
+    case "malformed_file":
+      return `Fix or remove the malformed ${reason.targetPath}, then re-run \`kordis pull\`/\`kordis update\`. Refusing to overwrite it blind \u2014 it may hold config from other tools/packages.`;
+    case "non_object_root":
+      return `${reason.targetPath} parses but its top level is not an object, so a config fragment can't be merged in. Move the file aside (or fix its shape), then re-run \`kordis pull\`/\`kordis update\`.`;
+    case "dangling_marker":
+      return `The file has a dangling <!-- kordis:${reason.fullSlug}:...:start --> marker. Delete that line (or restore its <!-- kordis:${reason.fullSlug}:end --> line), then re-run \`kordis pull\`/\`kordis update\`.`;
+  }
+}
+
 // src/commands/pull.ts
 async function requireExecutableApproval(pkg, fullSlug, files, approve2) {
   if (!pkg.capabilities.executable) return;
@@ -10796,7 +11025,12 @@ async function applyEmittedFile(abs, f, fullSlug, notes) {
     if (err.code !== "ENOENT") throw err;
   }
   if (f.format === "json" || f.format === "yaml" || f.format === "toml") {
-    const merged2 = mergeStructuredFile(existingRaw, f.content, f.format, abs);
+    let merged2;
+    try {
+      merged2 = mergeStructuredFile(existingRaw, f.content, f.format, abs);
+    } catch (err) {
+      throw adaptMergeRefusal(err) ?? err;
+    }
     if (existingRaw !== null && existingRaw.trim() !== "") {
       notes?.push(
         `merged into ${f.path} \u2014 comments/formatting in the existing file are not preserved`
@@ -10805,11 +11039,17 @@ async function applyEmittedFile(abs, f, fullSlug, notes) {
     await writeFile6(abs, merged2, "utf8");
     return;
   }
-  const merged = mergeFencedFile(existingRaw, fullSlug, f.content);
+  let merged;
+  try {
+    merged = mergeFencedFile(existingRaw, fullSlug, f.content);
+  } catch (err) {
+    throw adaptMergeRefusal(err) ?? err;
+  }
   await writeFile6(abs, merged, "utf8");
 }
 
 // src/commands/read.ts
+init_src2();
 init_sections();
 import { Command as Command6 } from "commander";
 
@@ -10829,6 +11069,15 @@ function untrustedFenceNotice(sentinel) {
 }
 
 // src/commands/read.ts
+var shellWord = (word) => /^[\w./@:+-]+$/.test(word) ? word : JSON.stringify(word);
+function readAgainCommand(fullSlug, parsed, opts) {
+  const suffix = parsed.version ? `@${parsed.version}` : parsed.range ? `@${parsed.range}` : "";
+  return [
+    `kordis read ${shellWord(`${fullSlug}${suffix}`)}`,
+    ...opts.pin === void 0 ? [] : [`--pin ${shellWord(opts.pin)}`],
+    ...opts.allowPending ? ["--allow-pending"] : []
+  ].join(" ");
+}
 function readCommand() {
   return new Command6("read").description("fetch a package body into the agent context (no install)").argument("<full_slug>", "package identifier {username}/{slug} or {username}/{slug}@{version}").option("--allow-pending", "allow versions whose AI review has not passed", false).option("--pin <semver>", "pin to an exact version (overrides @suffix)").option("--outline", "print only the section map (skeleton) \u2014 cheap on context", false).option("--section <name>", "print only one section (see names with --outline)").action(
     async (rawSlug, opts) => {
@@ -10906,9 +11155,19 @@ Bundled files \u2014 fetch with ${c.cyan(`kordis pull ${res.full_slug}`)}:
         const sec = sectionOf(res.body, opts.section);
         if (!sec) {
           const names = outlineOf(res.body).sections.map((s) => s.name).join(", ");
+          const readAgain = readAgainCommand(res.full_slug, parsed, opts);
+          if (isJsonMode()) {
+            throw new KordisApiError(400, {
+              error: {
+                code: "usage_error",
+                message: `section "${opts.section}" not found`,
+                hint: names ? `Available sections: ${names}. Read one with \`${readAgain} --section <name>\`.` : `This package has no sub-sections \u2014 read the whole body with \`${readAgain}\`.`
+              }
+            });
+          }
           process.stderr.write(
             `${c.red("\u2717")} section "${opts.section}" not found. Available: ${names || "(none \u2014 this package has no sub-sections)"}
-  See the map with ${c.cyan(`kordis read ${res.full_slug} --outline`)}.
+  See the map with ${c.cyan(`${readAgain} --outline`)}.
 `
           );
           process.exitCode = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayul/kordis",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "private": false,
   "description": "Command-line client for the Kordis registry — discover, install, and publish agentic-coding packages.",
   "license": "Apache-2.0",