@inkeep/open-knowledge 0.46.0-beta.7 → 0.46.0-beta.8

package/dist/assets/skills/project/references/onboard-existing-repo.md

@@ -0,0 +1,319 @@
+# Onboard an existing repo — convention extraction + link-graph activation
+
+Use this when (a) the user asks to set up an existing repo that already has content, OR (b) an `exec` directory listing shows content with no folder frontmatter / templates configured. Goal: **extract conventions from existing siblings + activate the link graph, leaving the repo more structured and more navigable than you found it.**
+
+This is the brownfield counterpart to `ok seed` (greenfield). Read the content directory from `config({ key: 'content.dir' })`; paths below are relative to it.
+
+Use OK primitives only — no new files outside `<folder>/.ok/`, no body rewrites without per-pair user confirmation.
+
+**Seven phases, in order. STOP gates require user confirmation before proceeding. Do not skip or batch ahead.**
+
+**Server requirement.** Phases 1-4 run fs-direct — `exec` (scan + read) and the `write`/`edit` verbs (folder frontmatter + templates) need no running server. Phase 5 (link-graph activation) composes `links` and `search`, which **require the OK Hocuspocus server** — Phase 5 step 0 checks for it and exits cleanly with a `run ok start` instruction if it is down.
+
+---
+
+## Phase 1 — Scan + classify (no user interaction, no server needed)
+
+1. `exec("ls -A <content-dir>")` — list every top-level entry.
+2. For each top-level **directory**: `exec("ls -A <dir>")` — the enriched listing surfaces the `.md` count, per-child frontmatter samples, recursive count, and the folder's own descriptive `title`/`description`/`tags` + `templates_available`.
+3. Classify each directory:
+   - **Substantial KB folder** — more than 3 `.md` files directly, OR named in a known-genre list: `specs/`, `reports/`, `docs/`, `articles/`, `research/`, `stories/`, `projects/`, `external-sources/`, `tech-probes/`, `rfcs/`, `proposals/`, `design-docs/`, `adrs/`.
+   - **Trivial folder** — 1-3 `.md` files; treat as one-offs.
+   - **Likely noise** — known build/vendored patterns: `node_modules/`, `dist/`, `build/`, `vendor/`, `third_party/`, `.changeset/`, `coverage/`.
+4. Detect total `.md` count across the content root.
+5. Detect a seeded layout: do any of `external-sources/`, `research/`, `articles/` exist? (Informational only.)
+6. **Confirm-then-extend detection.** For each substantial folder, check the `exec("ls -A <folder>")` listing:
+   - If the folder already has a `title`/`description`/`tags` → descriptive folder frontmatter already exists; switch THAT folder to "extend mode" (propose additions, not replacement).
+   - If `templates_available` is non-empty → a template already exists for that folder; skip template extraction for it.
+   - If MOST substantial folders are already configured → set up to exit early at Phase 7 with "already configured."
+
+**Early-exit conditions:**
+- If total `.md` count is **fewer than 5** → STOP. Tell the user "this looks empty — try `ok seed` for a greenfield starter pack, OR write your first doc and come back later." Exit.
+- If all-greenfield-already (per step 6) → STOP. Exit with "already configured."
+
+---
+
+## Phase 2 — Confirm scope (STOP gate 1)
+
+Present a structured summary to the user. Example:
+
+```
+Orientation — what I found:
+
+Substantial folders (candidate KB content):
+  - specs/      52 .md   (suggests spec collection)
+  - reports/   134 .md   (suggests research collection)
+  - stories/    19 .md
+  - projects/    8 .md
+
+Trivial folders (one-offs):
+  - tech-probes/  4 .md
+  - 14 root-level docs (README, AGENTS, CLAUDE, CI, CONTRIBUTING)
+
+Likely noise (recommend .okignore):
+  - node_modules/  ~200 .md  (vendored deps)
+  - dist/           ~30 .md  (build outputs)
+  - Per-package CHANGELOG.md  (generated)
+
+Seeded layout: no external-sources/ / research/ / articles/ present.
+
+Mark each substantial folder as:
+  [KB]    knowledge-base content — extract conventions, add folder frontmatter + template
+  [skip]  already-structured or out of scope — leave existing settings
+  [noise] add to .okignore
+```
+
+**Wait for user response. Do not proceed until each substantial folder is classified.**
+
+---
+
+## Phase 3 — `.okignore` curation (STOP gate 2)
+
+Based on user `[noise]` marks + agent-detected patterns, propose `.okignore` entries:
+
+```
+Proposed .okignore additions:
+  node_modules/**/*.md          # vendored dep READMEs
+  dist/**/*.md                  # build outputs
+  **/CHANGELOG.md               # per-package generated changelogs
+  THIRD_PARTY_NOTICES.md        # auto-generated notices
+  <any user-marked folders>
+```
+
+Ask the user: "Apply these `.okignore` additions? (yes / edit list / skip)"
+
+On confirm: read the existing `.okignore`, append new entries, write via native `Write` (`.okignore` is a plain config file, not in-scope markdown — escape-hatch ok).
+
+**Don't redundantly propose what `.gitignore` already covers.** `.gitignore` and `.okignore` evaluate together; if the repo's `.gitignore` already excludes `node_modules/`, you don't need to add it again.
+
+---
+
+## Phase 4 — Per-folder convention extraction (STOP gates 3 + 4)
+
+For **each** folder the user marked `[KB]`:
+
+1. **Pick representative siblings.** From `exec("ls -A <folder>")`:
+   - Most-recently-edited doc
+   - Median-sized doc (roughly: pick the middle entry)
+   - Up to 3 siblings. If the folder has fewer than 2 siblings, skip template extraction; only propose folder frontmatter.
+
+2. **Read the siblings.** `exec("cat <doc>")` on each. Extract:
+   - **Heading set** — list every top-level heading (a line starting with `# ` or `## `) in document order.
+   - **Frontmatter shape** — which keys appear in at least 2 of the 3 siblings. Note ALL recurring keys, but route them by purpose: keys that describe the FOLDER (`title` / `description` / `tags`, though any key is allowed) go in the folder frontmatter; recurring per-doc keys (`status:`, `owner(s):`, `baseline-commit:`) are starting values for NEW docs and belong in the folder's TEMPLATE. Folder frontmatter is open-shape (like a doc's) but self-only — it does NOT flow into child docs, so per-doc starting values still belong in the template.
+   - **Filename pattern** — dated (`YYYY-MM-DD-*`)? Slugged? Sequential?
+   - **Link patterns in body** — does the body have a "Related" / "See also" / "References" section? Note the convention.
+
+3. **STOP gate 3 — heading-set match check.** If top-level headings DON'T match in text + order across at least 2 siblings, do NOT extract a template — only propose folder frontmatter. Tell the user: "siblings in `<folder>` don't share a consistent body skeleton; skipping template, proposing folder frontmatter only." The operational metric for "match" is **heading-text equality** (exact strings, in order). Anything beyond that is model judgment and shouldn't pretend to be deterministic.
+
+4. **Idempotency check.** Per Phase 1 step 6:
+   - If this folder already has its own frontmatter → switch to "extend mode." Show existing keys to the user; propose ADDITIONS only.
+   - If `templates_available` includes a template → skip template extraction. Tell the user: "existing template `<name>` found; preserving."
+
+5. **Propose folder frontmatter + template.** One `write`/`edit` call per target:
+
+   ```ts
+   // Folder frontmatter → writes <folder>/.ok/frontmatter.yml.
+   // Open-shape (any key, like a doc's); here the conventional
+   // title/description/tags describing the FOLDER. Self-only — does NOT
+   // cascade into child docs. Use `write({ folder })` for a new folder,
+   // `edit({ folder })` to add keys to an existing one (merge-patch).
+   edit({
+     folder: {
+       path: '<folder>',
+       frontmatter: {
+         title: '<inferred>',          // e.g., "Specifications"
+         description: '<inferred>',    // 1-2 sentences describing the folder's purpose
+         tags: ['<inferred>'],         // e.g., ['spec']
+       },
+     },
+   })
+
+   // Template → writes <folder>/.ok/templates/<name>.md. This is where
+   // recurring per-doc starting values live (status, owner, ...) — bake them
+   // into the template body's frontmatter region so new docs start with them.
+   write({
+     template: {
+       path: '<folder>/<inferred-name>', // e.g., 'specs/SPEC', 'reports/REPORT'
+       frontmatter: { title: '<placeholder>', description: '<placeholder>' },
+       content: '<heading skeleton from siblings; include a frontmatter region with recurring per-doc keys (status, owner, ...) as starting values>',
+     },
+   })
+   ```
+
+6. **STOP gate 4 — surface the proposal.** Show: heading set + frontmatter shape + filename pattern + link patterns. Ask: "Apply this proposal? (yes / edit / skip this folder)"
+
+7. **Apply confirmed proposals** via the `edit({ folder })` + `write({ template })` calls above. Re-run `exec("ls -A <folder>")` to confirm `templates_available` + the folder's descriptive `title`/`description`/`tags` are populated.
+
+Repeat for every `[KB]` folder.
+
+**Scope note:** do NOT attempt nested-pattern detection (e.g. applying the same folder frontmatter across `specs/*/evidence/` for every spec's evidence subfolder). Each folder is addressed by its own path — one `edit({ folder })` call per folder. Users who want nested folder frontmatter set it up manually afterward.
+
+---
+
+## Phase 5 — Link-graph activation
+
+The largest phase. Uses the `links` tool (every link-graph view) plus `search` and `edit` to apply confirmed link insertions.
+
+0. **Server check (required for this phase).** `links` and `search` need the OK Hocuspocus server. Probe via `links({ kind: "hubs" })`. If the response starts with `"Error: Hocuspocus server is not running"`, STOP — tell the user "the link-graph phase needs the OK server. Start it with `ok start` from a terminal, then resume here (Phases 1-4 are already applied)." Exit cleanly.
+
+Six sub-passes, each with its own STOP gate.
+
+### 5a. Orphan triage (STOP gate 5a)
+
+1. Run `links({ kind: "orphans" })`.
+2. For each orphan, run `links({ kind: "suggest", docName: <orphan> })`:
+   - If `mentions[]` is non-empty → there are docs that mention this orphan without linking. Adoption candidates.
+   - If `mentions[]` is empty → the orphan is **genuinely standalone** (no other doc references it at all). Surface as: "this looks intentionally standalone (e.g., a README). Skip / adopt anyway by linking from a hub / add to `.okignore`?"
+3. Confirm per orphan. For each "link" choice, `edit({ document: { path, find, replace } })` on the source doc — find the existing mention text `links({ kind: "suggest" })` surfaced and replace it wrapped in link syntax.
+
+**Note on re-surfacing:** "intentional standalone" markers are not persisted. Each re-run surfaces the same intentional orphans (root `README.md`, `CONTRIBUTING.md`, etc.) and the user re-dismisses them. Acceptable minor friction.
+
+### 5b. Hub identification (STOP gate 5b)
+
+1. Run `links({ kind: "hubs" })` — surfaces the most-linked-to docs (highest *inbound* links), i.e. pages already acting as hubs.
+2. For each substantial `[KB]` folder (those that got templates in Phase 4):
+   - Check whether a hub already exists (`<folder>/README.md`, `<folder>/INDEX.md`, `<folder>/CATALOGUE.md`).
+   - If yes: don't create a new one (anti-pattern: don't create INDEX.md hubs).
+   - If no: ensure the template extracted in Phase 4 includes a `## Related` / `## See also` section. If the template doesn't already have one, propose adding it.
+3. Surface existing hubs to the user so they know what the link graph already provides.
+
+### 5c. Dead-link sweep (STOP gate 5c)
+
+1. Run `links({ kind: "dead" })` (no `sourceDocNames` → audits the whole corpus).
+2. For each dead link, propose: a fix candidate (via `search` for the correct target), or deletion (remove the link, or the prose around it). Leaving it as an "intentional redlink" is not an option — every dead link is fixed or removed.
+3. Confirm per dead-link. Apply confirmed fixes via `edit`.
+
+### 5d. Untextualized-reference detection (STOP gate 5d)
+
+`links({ kind: "suggest" })` implements server-side detection of prose mentions of a target doc that aren't wrapped in link syntax. Lean on it directly.
+
+1. For each substantial `[KB]` doc, run `links({ kind: "suggest", docName: <target> })`.
+2. Each call returns `mentions[]` with `{ source, excerpt, offset }` — places to insert links pointing TO this target from OTHER docs.
+3. Surface batched **by source doc** (not per-link, to keep cognitive load reasonable):
+
+   ```
+   In specs/2026-04-23-foo/SPEC.md, found 3 untextualized references:
+     line 12: "the existing `ok init` scaffolds..." → matches code, NOT a doc — skip
+     line 145: "...replaces the instructional init-content tool" → matches a spec — accept as link
+     line 203: "...per AGENTS.md ecosystem convention" → matches root AGENTS.md — accept as link
+   ```
+
+4. Confirm per source doc (batched). Apply confirmed link insertions via `edit({ document: { path, find, replace } })` — find the mention text the `suggest` view surfaced and replace it wrapped in link syntax.
+
+**Truncation handling:** if the `suggest` view returns `truncated: true`, the scan hit its time budget. Iterate with smaller scope or accept partial coverage and tell the user.
+
+### 5e. Vague-referential detection (STOP gate 5e)
+
+Harder case: prose discusses a concept covered by another doc without naming it. Example: a spec talks about "how we track who wrote what" and there's an `agent-identity-attribution/REPORT.md` covering exactly that — but the spec never says "agent identity attribution." `links({ kind: "suggest" })` (title/alias match) misses this; semantic detection requires model judgment.
+
+1. For each substantial doc, identify its main concepts. Use frontmatter `subjects:` / `topics:` if present; else extract from heading text + the first 2-3 paragraphs.
+2. For each concept, run `search({ query: <concept> })`. Take the top 1-2 non-self results.
+3. For each candidate sibling:
+   - Verify it is NOT already linked from this doc (`links({ kind: "forward", docName: <doc> })`).
+   - Verify the content is actually relevant (re-read the summary).
+4. Surface to the user with brief justification per pair. Confirm. Apply via `edit` (insert the link in a "Related" or "References" section).
+
+**Caveat:** vague-referential is judgment-heavy. False positives are expected; the user is the final arbiter. If the user rejects more than half the proposals in a batch, recalibrate (tighten concept-extraction, raise the relevance bar).
+
+### 5f. Link-style detection + standardization (STOP gate 5f)
+
+1. Sample 10 random non-noise docs (or all if the total is under 10). Count occurrences:
+   - Wiki-link syntax: `[[Page Title]]` (legacy)
+   - Relative-markdown: `[text](./path.md)` or `[text](path.md)` (the current OK recommendation)
+2. Report the ratio to the user. If mixed, propose a one-time standardization: convert all `[[Page]]` to relative-markdown links. Ambiguous `[[Page]]` (multiple matching files) → surface for confirmation.
+3. Apply via `edit` on each affected doc, resolving page titles to file paths via `exec("ls -A")` / `search`.
+
+---
+
+## Phase 6 — Apply + validate
+
+After all confirmed proposals are applied:
+
+1. Re-run `exec("ls -A <folder>")` on every `[KB]` folder. Verify:
+   - the folder's descriptive `title`/`description`/`tags` are populated (folder frontmatter landed)
+   - `templates_available` includes the new template (template landed)
+2. Re-run the orphan + dead-link audit in one call — `links({ kind: ["orphans", "dead"] })`. Confirm the orphan count dropped vs. the Phase 5a baseline and that fixed dead links no longer report.
+
+If any validation step fails, surface it to the user — do NOT silently pass.
+
+---
+
+## Phase 7 — Final summary + exit
+
+Share a structured summary with the user. Distinguish initial-setup mode from extension mode (per Phase 1 step 6):
+
+**Initial-setup mode:**
+
+```
+Onboarding complete:
+
+Folder frontmatter added (<folder>/.ok/frontmatter.yml):
+  specs/                  title: Specifications, tags: [spec]
+  reports/                title: Research Reports, tags: [report]
+  stories/                title: User Stories, tags: [story]
+  projects/               title: Projects, tags: [project]
+
+Templates added (<folder>/.ok/templates/<name>.md):
+  specs/.ok/templates/SPEC.md     (heading skeleton from 3 siblings, link-aware)
+  reports/.ok/templates/REPORT.md (heading skeleton from 3 siblings, link-aware)
+
+.okignore additions: 4 entries (node_modules, dist, CHANGELOG.md, THIRD_PARTY_NOTICES.md)
+
+Link-graph activation:
+  Orphan triage:          7 orphans triaged (4 adopted, 3 left as intentional standalones)
+  Hub identification:     3 existing hubs surfaced; 2 templates updated with `## Related` sections
+  Dead-link sweep:        5 dead links — 4 fixed, 1 removed
+  Untextualized refs:     12 prose mentions linked (across 8 source docs)
+  Vague-referential:      5 semantic cross-references added (across 4 source docs)
+  Link-style:             standardized 42 wiki-links to relative-markdown
+
+Notes:
+  - 3 intentional standalones (README, CONTRIBUTING, LICENSE) re-surface on each run.
+    No "standalone" marker is persisted; you'll re-dismiss them next time.
+
+Next steps:
+  - Review the extracted templates in <folder>/.ok/templates/ — they're starter shapes, not finished.
+  - The next agent in this repo will see templates_available + the folder's own frontmatter for every KB folder.
+  - Re-run after significant content additions (new folder categories, major restructures).
+```
+
+**Extension mode** (when prior configuration was detected):
+
+```
+Onboarding extension complete (existing configuration preserved):
+
+New folder frontmatter:
+  tech-probes/            (was missing — title: Tech Probes, tags: [probe])
+
+Updated templates:
+  specs/.ok/templates/SPEC.md   (heading skeleton refreshed from current siblings)
+
+Link-graph activation:
+  Orphan triage:          3 new orphans found (all triaged)
+  Untextualized refs:     8 new references linked
+```
+
+---
+
+## STOP rules / anti-patterns (load-bearing across phases)
+
+- **Don't restructure existing folders** — no renaming, moving, consolidating, splitting. The folder shape as-found is the contract.
+- **Don't impose a starter-pack layout** — only propose `external-sources/` / `research/` / `articles/` if the user explicitly opts in. Most brownfield repos won't.
+- **Don't create INDEX.md / README.md hub files** — folder frontmatter + `exec("ls -A")` give the same view live.
+- **Don't extract templates from a single sibling** — you need at least 2 with a matching heading set (heading-text equality, in order).
+- **Don't bulk-rewrite doc bodies** — every link insertion (5a, 5c, 5d, 5e, 5f) goes through user confirmation via STOP gates.
+- **Don't auto-apply** — every phase has a confirmation gate. You propose; the user disposes.
+- **Don't run if the project has fewer than 5 `.md` files** — exit early; redirect to `ok seed`.
+- **Don't run if the project is already fully configured** — exit early with "already configured."
+- **Don't redundantly propose what `.gitignore` covers** in `.okignore`.
+- **Don't attempt nested-pattern detection** — each substantial top-level folder gets its own folder frontmatter; nested sub-patterns (`specs/*/evidence/`) are left for users to set up manually.
+
+---
+
+## Exit conditions (early termination)
+
+- **Empty project** (Phase 1): fewer than 5 `.md` files total → exit with "try `ok seed` instead."
+- **All-greenfield-already** (Phase 1 step 6): folder frontmatter exists AND templates exist for every substantial folder → exit with "this project is already configured."
+- **Server down** (Phase 5 step 0): Phases 1-4 already applied fs-direct; surface "the link-graph phase needs `ok start` running" and exit cleanly — resuming picks up at Phase 5.
+- **User aborts at any STOP gate** → exit cleanly, leaving any already-applied proposals in place (apply is per-phase, not all-or-nothing).
+- **Validation failure** (Phase 6) → don't pretend to succeed; surface the failed step to the user.

package/dist/assets/skills/project/references/preview.md

@@ -57,7 +57,7 @@ Warnings fire at most once per session in the fresh-start case.
 
 **Re-point at the end of a multi-doc workflow; don't claim a doc is on screen unless you put it there.** The one-shot attach (signal 3) opens the preview *once* — later writes do NOT move the pane; it stays on the doc you last navigated to. When a turn touches several docs, finish by navigating the preview to the doc the user should land on, using your host's move mechanism (`preview_url` → navigate your in-app browser; honor `autoOpen`). Until you have navigated there *this* turn, don't tell the user a doc is "open" / "on screen" — at most, say the preview may still be on the doc you opened earlier.
 
-**`previewUrl: null` only means "no UI reachable" on the two attach-warning tools: `write` / `edit`.** Workflow tools return prose and don't carry `previewUrl`. `delete` / `move` emit `previousPreviewUrl` (different field, for closing stale tabs) and don't fire attach warnings. `preview_url` auto-starts the backend on demand (same `OK_MCP_AUTOSTART` gate as writes; a cold first call can take seconds) and reports `running: false` + `url: null` only when no UI could be reached — its hint names the right command.
+**`previewUrl: null` only means "no UI reachable" on the two attach-warning tools: `write` / `edit`.** `delete` / `move` emit `previousPreviewUrl` (different field, for closing stale tabs) and don't fire attach warnings. `preview_url` auto-starts the backend on demand (same `OK_MCP_AUTOSTART` gate as writes; a cold first call can take seconds) and reports `running: false` + `url: null` only when no UI could be reached — its hint names the right command.
 
 If you see `"Hocuspocus server is not running"`, run `ok start` and retry.
 

package/dist/assets/skills/project/references/setup.md

@@ -24,3 +24,9 @@ ok start
 ## Rung 3 — Desktop app, optional
 
 For a native editor with the file tree, property panel, and built-in preview, install the OK Desktop app. The quickstart link above has the current download — it tracks the latest release, so grab it there rather than from a pinned URL.
+
+## Tool visibility — before you conclude the MCP is missing
+
+**MCP tool visibility — not seeing `exec` is NOT the escape hatch.** MCP wiring varies by client (Claude Code, Cursor, Codex, Windsurf, VS Code). Server labels are user-defined; tools may not appear as top-level symbols named `exec`. If OpenKnowledge is registered as an MCP server here, route markdown reads through its `exec` / `search` via your client's documented MCP invocation (including any generic "call MCP tool" flow). Registration is the test, not top-level-symbol visibility.
+
+**Your initial tool list is NOT exhaustive — run tool discovery before concluding the MCP is missing.** Some clients (notably Codex) defer MCP tools behind a lazy `tool_search` / tool-discovery step, so `mcp__open-knowledge__*` is absent from the upfront tool set and only appears after you search for it. Absence from the visible list means "I have not discovered it yet," NOT "it is not registered." If you don't see the tools, your first move is to run your client's tool-discovery / `tool_search` for `open-knowledge` (or `exec` / `search` / `write`) — do not infer unavailability from the initial list.

package/dist/assets/skills/project/references/starter-packs.md

@@ -0,0 +1,41 @@
+# Knowledge layers + starter packs — depth
+
+(Core carries the layer table. This file carries the operating detail.)
+
+## The layer model
+
+Three of the layers correspond to [Karpathy's three-layer knowledge-base pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): **ingest** (raw sources, immutable) → **research** (wiki, provisional) → **consolidate** (wiki, canonical). Onboarding an existing repo operates one level up, at the project-metadata layer, and is the brownfield counterpart to the greenfield `ok seed` CLI.
+
+Typical day-2 flow: user shares a URL → ingest (preserve) → user asks "now research this" → research (provisional article; ingests more sources as needed) → decision lands → consolidate (canonical article, supersedes the research).
+
+**None of these are MCP tools.** They are procedures that ship as skill guidance, in one of two shapes: a **reference file** inside a skill's bundle, which you open by path once that skill is loaded; or a **skill of its own**, which loads on description match when its pack is seeded.
+
+- ingest → reference file `ingest-and-sources.md`, here in this bundle. Ships with every `ok init` because Core's Grounding rule depends on it, pack or no pack.
+- onboard a repo that already has content → reference file `onboard-existing-repo.md`, here in this bundle.
+- research / consolidate → their own skills, `open-knowledge-pack-knowledge-base-research` and `open-knowledge-pack-knowledge-base-consolidate`, installed alongside their pack by `ok seed --pack knowledge-base`. **Not available otherwise** — if the pack isn't seeded, say so rather than improvising a lookalike pipeline.
+- generate / refresh a codebase wiki → reference file `generate-and-refresh.md`, inside the `open-knowledge-pack-codebase-wiki` skill's bundle and readable once that skill loads. Installed by `ok seed --pack codebase-wiki`.
+
+Read the relevant procedure and execute its numbered steps with the OK verbs; don't skip its STOP gates.
+
+**Autonomy gates vs session-level autonomy.** A procedure's STOP gates (research's scoping gate, consolidate's decision-confirmation gate) are not overridden by session-level "work without stopping for clarifying questions" hints. The session-level hint covers trivial back-and-forth ("which file did you mean?"); the gates exist for one-way-door decisions where the procedure deliberately wants confirmation before continuing. When in doubt, treat the gate as authoritative and the session-level autonomy hint as a default for the in-between turns.
+
+**Do not chain silently.** After ingest, ask the user whether to proceed to research. After research, let the user decide whether the findings are ready to consolidate. Each procedure completes on its own terms — the user drives the transitions.
+
+**Project scaffolding — two paths.** **Empty repo:** run `ok seed` once from a terminal (scaffolds the layout + seeds `log.md` + folder defaults). **Existing content:** work through `onboard-existing-repo.md`. Neither is required; the layer procedures work against any folder structure. Only mention each when explicitly relevant.
+
+## Starter packs — reference for inspiration
+
+The `ok` CLI (a Bash surface beside the MCP tools; other verbs `ok start` / `ok open` are documented in the core) ships proven layouts you can study to build a *similar* structure of your own — adapt the idea, don't clone the pack:
+
+- `knowledge-base` — source-grounded research articles
+- `software-lifecycle` — proposals, decisions, specs
+- `codebase-wiki` — agent-authored wiki of your codebase
+- `plain-notes` — notes + daily journal
+- `worldbuilding` — fiction story wiki
+- `writing-pipeline` — drafts → published
+- `entity-vault` — people / companies / meetings (personal CRM)
+- `okf` — Open Knowledge Format–conformant base
+
+A pack that ships skills installs them project-local when seeded. Those skills are where the pack's procedures live; a pack may ship one skill or several.
+
+To reference one **without installing it**: `ok seed --list-packs` (the menu) → `ok seed --pack <name> --dry-run` (its folders + the *why* of each folder + templates; writes nothing). Then either adapt the ideas into your own folders (`write({ folder })` + a template) or adopt the pack as-is by re-running without `--dry-run`. Reach for this when a user wants structure and an archetype fits — propose a tailored variant, not a verbatim copy.

package/dist/assets/skills/write-skill/SKILL.md

@@ -3,7 +3,6 @@ name: open-knowledge-write-skill
 description: "Use when the user wants to create, author, write, or design a new Agent Skill (a SKILL.md) — for OpenKnowledge or for their editors — including requests like 'help me write a skill', 'make a skill that…', 'turn this workflow into a skill', or improving an existing skill's triggering and discipline. Also use when capturing reusable agent guidance that should live as an installable skill rather than a one-off prompt. Covers choosing scope (project vs global), the SKILL.md frontmatter contract, progressive-disclosure structure, evaluating the skill, and installing it into the user's editors."
 compatibility: "OpenKnowledge project recommended (uses the `write` / `edit` / `install` MCP verbs). Authoring + validation are pure file ops; live preview + eval want a running server (`ok start`)."
 metadata:
-  version: "0.45.0"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---
@@ -23,14 +22,35 @@ it says. Work the stages below in order, but jump to where the user already is.
 
 ## Stage 1 — Capture intent and classify the skill
 
-**Gate — does this already exist? Check BEFORE you build.** Scan the installed
-skills (the host surfaces the full catalog when this skill loads) for one whose
-role or triggers already cover the task. If an existing skill covers most of it,
-STOP and **recommend reuse** — a near-duplicate with overlapping triggers
-mis-fires and dilutes both. Build a new skill only when it is genuinely distinct,
-or a deliberately tighter companion whose `description` explicitly hands off to
-the existing one. Surface the overlap and decide WITH the user before drafting or
-writing anything — never discover it after the skill is written.
+**Gate — does this already exist? Check BEFORE you build.** First list managed
+skills with `skills({})`, then read any likely match with `skills({ name })`;
+these are the Project/Global skills OpenKnowledge already manages. Also search
+the public marketplace with `skills({ query: "<2-4 trigger words>" })` before
+drafting when the task sounds reusable beyond this project. Each marketplace row
+returns `name`, `source`, and `description`; inspect the strongest descriptions,
+then import a chosen candidate with `import({ source, skill: name, add: [...] })` and adapt
+it only if reuse is the right call. Use the Vercel `find-skills` skill,
+`npx skills find <query>`, or manual skills.sh search only when the OK MCP
+`skills({ query })` path is unavailable. If the user already has a skills.sh page
+open, pass the full skill-page URL as `source`, e.g.
+`import({ source: "https://www.skills.sh/<publisher>/skills/<skill>", add: [...] })`. Do not
+run `npx skills add` as the
+default install path in this flow: import through OpenKnowledge
+(`import({ source, skill, add })`) so the skill lands as a real folder with
+provenance, versioning, and managed fan-out; `add` says where it goes, and
+`install` afterwards changes where it lives. Use 2-4 concrete trigger phrases from the user's request plus
+the domain or tool name, then open/read the strongest candidates' descriptions
+before judging. If an existing or public skill covers most of it, STOP and
+**recommend reuse** — a near-duplicate with overlapping triggers mis-fires and
+dilutes both. If a public skill is close but not exact, decide WITH the user
+whether to import/adapt it into OpenKnowledge, install it outside OK with the
+Skills CLI, or write a narrower companion whose `description` explicitly hands
+off to it. Build a new skill only when it is genuinely distinct. Surface the
+overlap and the installed-skill plus marketplace search outcome before drafting
+or writing anything. This is a disclosure gate: tell the user what you checked,
+what matched, and why reuse/import/adapt/new-skill is the right next step. Never
+discover overlap after the skill is written. If `skills({ query })` / skills.sh
+is unreachable, say so plainly and continue with the installed-skill check.
 
 Ask only what you can't infer:
 
@@ -47,13 +67,13 @@ Ask only what you can't infer:
 
 ## Stage 2 — Resolve scope FIRST (never infer silently)
 
-Scope determines where the skill lives and where `install` projects it. This is
+Scope determines where the skill lives and where `install` fans it. This is
 the user's decision and has different blast radius — make it explicit.
 
-| Scope | Lives in | `install` projects to |
+| Scope | Lives in | `install` fans it to |
 | --- | --- | --- |
-| **Global** | `~/.ok/skills/<name>/` (your user store) | your editors, in **every** project |
-| **Project** | `<kb>/.ok/skills/<name>/` (this KB, shared via git) | this project's editors; teammates get it on `git pull` |
+| **Global** | a real folder under your home's skill roots (e.g. `~/.claude/skills/<name>/`) | your editors, in **every** project |
+| **Project** | a real folder in this repo's skill roots (e.g. `.claude/skills/<name>/` or the `.agents/skills/` hub — shared via git) | this project's editors; teammates get it on `git pull` |
 
 Default heuristic: inside an OK project and the task is specific to it → **project**;
 "for all my work / globally" → **global**; otherwise ask one question. State the
@@ -80,10 +100,10 @@ choice and its consequence before writing.
 Before writing the skill, run the scenario WITHOUT it and capture what the agent
 does wrong — verbatim, including its rationalizations ("the test is trivial so I
 skipped it"). Those rationalizations are the exact loopholes the skill body must
-close. If you have a running server, use the agent simulator
-(`cd packages/app && pnpm exec tsx src/server/agent-sim.ts`) as the executor; otherwise
-reason through the baseline transcript with the user. Skip this stage for plain
-reference skills.
+close. Run the scenario in a fresh agent session with the skill absent — a new
+chat, a sub-agent, or a second terminal — and keep the transcript; if you have no
+way to run it clean, reason through the baseline with the user instead. Skip this
+stage for plain reference skills.
 
 ## Stage 5 — Draft the skill
 
@@ -149,26 +169,47 @@ load the skill. Get it right (`references/description-optimization.md`):
 - Sanity-check against near-miss queries: phrasings that SHOULD trigger it and
   adjacent ones that should NOT.
 
-## Stage 8 — Install (the deliberate Draft → Installed step)
+## Stage 8 — Install (choose where it's available)
 
-Drafting doesn't change the agent's behavior until you project it:
+The skill is already live for whichever agent reads the folder it was created
+in — its own folder IS the skill (there is no draft state). `install` manages
+WHERE ELSE it is available, additively:
 
 ```
-install({ name: "<name>" })
+install({ name: "<name>", add: ["codex", "opencode"] })   // add locations
+install({ name: "<name>", remove: ["codex"] })            // remove locations
+install({ name: "<name>", add: ["codex"], mode: "link" }) // ...as a symlink
+install({ name: "<name>", convert: ["codex"], mode: "copy" })  // change one location's form
+install({ name: "<name>", source: ".team/skills" })       // move the real folder (run alone)
 ```
 
-This fans the validated skill into the project's configured editors
-(`.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/`, `.pi/skills/`). For a project skill,
-commit `.ok/skills/<name>/` and the projections so teammates get it on pull. Edit
-later with `edit({ skill })` then `install` again; `delete({ skill })` removes it
-and uninstalls. Roll back a **project** skill with `history({ skill })` →
-`restore_version({ skill, version })` — global skills are unversioned in this
-build, so they have no history to restore.
+Location ids are editor host ids (`claude` … `pi`), `agents` (the
+vendor-neutral hub), or a custom root path like `.team/skills`.
+
+**Which form a location takes.** `mode` applies only to the locations the call
+names — those in `add`, or those in `convert` — and to nothing else. Omit it on
+`add` and the new location takes the form the skill already uses. There is no
+skill-wide mode: installing never rewrites a location you did not name.
+Changing an existing location is `convert`, which leaves membership alone; pass
+every location to make them uniform.
+
+**What each form means.** A symlink points at the source, so it cannot drift. A
+copy is its own folder and refreshes automatically from the source — until
+someone hand-edits it, at which point it forks and is never overwritten again.
+
+**Lifecycle.** Edit with `edit({ skill })`; it routes to the source and versions
+in place. There is no "uninstall everywhere" — removing every other location
+still leaves the source folder loading for its agent, and a skill stops existing
+only via `delete({ skill })`, which removes the source and every location. Roll
+a **project** skill back with `history({ skill })` → `restore_version({ skill,
+version })`; global skills are unversioned in this build. For a project skill,
+commit the skill folders — they are ordinary files in git, so teammates get them
+on pull.
 
 ## Reminders
 
 - Prefer ONE good skill over many overlapping ones; split only when triggers diverge. (The Stage 1 gate is where you ENFORCE this — don't leave overlap to discover later.)
-- Scope is the only placement decision — don't fold harness/format/toolchain assumptions into it, and don't bake one into the scope question's wording. You are authoring an OpenKnowledge skill: write it with `write({ skill })` and project it with `install`; never hand-write skill files into editor dirs (`.claude/skills/`, `.cursor/skills/`, `.codex/skills/`) — `install` owns those and overwrites them. If you load this flow, author through it.
+- Scope is the only placement decision — don't fold harness/format/toolchain assumptions into it, and don't bake one into the scope question's wording. You are authoring an OpenKnowledge skill: create it with `write({ skill })` — it lands as a real folder at the project's default skill home with attribution and versioning — and fan it out with `install`; don't hand-scatter copies across editor dirs, because `install` owns fan-out and refreshes unedited copies from the source (a hand-edited copy forks and stops refreshing). If you load this flow, author through it.
 - Ground claims about how skills behave (versioning, install targets, scope semantics) in this guide or the tool descriptions — don't assert system facts from assumption.
 - Avoid blanket ALWAYS/NEVER rules without a stated reason — they read as noise and
   get ignored. Explain the why.

package/dist/assets/skills/write-skill/references/pressure-testing.md

@@ -33,8 +33,9 @@ A short table the agent reads when tempted:
 
 ## Running it
 
-With a server: drive the scenarios through the agent simulator
-(`cd packages/app && pnpm exec tsx src/server/agent-sim.ts`). Without one: walk the
-pressured prompt with the user and read the response for the rule holding.
+Drive each scenario through a fresh agent session (a new chat, a sub-agent, or a
+second terminal) so nothing from this conversation leaks in. If you cannot run
+one, walk the pressured prompt with the user and read the response for the rule
+holding.
 Read the full transcript, not just the final answer — discipline fails in the
 reasoning, not always in the output.