knosky 0.6.3 → 0.7.0

package/README.md

@@ -1,117 +1,170 @@
-# KnoSky
-
-*Your knowledge as a skyline.*
-
-**Turn any repo or folder of docs into a living, explorable city — and give your AI assistant grounded, cited answers from your own source. Runs entirely on your machine. Free.**
-
-> *Born from building [Sathia](https://sathia.ai).*
-
----
-
-## See it in 10 seconds
-
-Open **[`demo/knosky-demo.html`](./demo/knosky-demo.html)** in your browser (just double-click it — it's a single self-contained file). That's a sample project rendered as a city. Now point it at your own.
-
----
-
-## The problem
-Your project grows faster than anyone can hold in their head. Hundreds of files, decisions, and docs across folders. A file tree tells you what files exist — not what the *system* is. So things get lost, decisions get re-litigated, and your AI assistant confidently makes things up about your own codebase.
-
-## What you get (the outcome)
-
-> **Measured (SAT-439, 5 tasks, naive agent vs. KnoSky-guided agent):**
-> **68% fewer tokens · 70% fewer tool calls · 6× faster to the right file**
-> *(All guided runs answered correctly; the naive agent found the target in 3 of 5 tasks and answered correctly in 0.)*
-
-- **See your whole project in one screen.** Instead of scrolling a file tree, you see the *shape* of everything — which areas are big, how they connect, where the gaps are. New collaborators get oriented in minutes, not weeks.
-- **Find anything in seconds.** Search the city — or ask your assistant *"where does auth live / what did we decide about billing"* — and jump straight to the **live file**.
-- **Your AI answers from YOUR source, with citations.** Connect it to Claude / Cursor / VS Code / Gemini and your assistant stops guessing about your codebase — it cites the real file, every time.
-- **Zero setup tax, local-first by default.** Point it at a folder → a city in under a minute. Deterministic, **$0 tokens** to keep fresh, **nothing ever leaves your machine**, and a fail-closed secret scan before you share. (KnoSky does not claim "zero data risk" — see [PRIVACY.md](./PRIVACY.md).)
-
-**Net:** faster comprehension, reliable recall of your own knowledge, and a grounded AI — without giving up privacy or paying a cent.
-
-## Who it's for
-Developers, founders, and architects sitting on a sprawling repo or knowledge base who want to *understand and navigate their own work fast* — and want their AI assistant grounded in it — without uploading anything.
-
----
-
-## How it works
-
-**Quickstart — one command:**
-```bash
-npx knosky .
-```
-Indexes the current folder, opens the city, prints the MCP config for your AI assistant (Claude Code / Claude Desktop / Cursor / VS Code) plus a few starter prompts, and starts the local connector. Point it anywhere with `npx knosky /path/to/your/repo`. Flags: `--no-open`, `--no-serve`.
-
-Prefer a clone? `git clone https://github.com/SathiaAI/knosky && cd knosky && npm install && node bin/knosky.mjs .`
-
-Want the individual pieces instead? Read on.
-
-**Requirements:** [Node.js](https://nodejs.org) 18+.
-
-**1. Build your city from a folder or repo**
-```bash
-node core/fs-indexer.mjs --root /path/to/your/repo --out city-data.json --share-safe
-node renderer/build-rich.mjs city-data.json city.html
-```
-Open `city.html`. Every top-level folder is a **district**, every file a **building**, every building links to the real source.
-
-**Flags:** `--share-safe` strips your absolute path (basename only) and prints a safety report — and the build **fails closed** if a secret-like value is detected. `--redact AcmeCorp,SecretProject` masks (and skips files matching) project-specific terms. `--include-absolute-root` keeps the full local path (private diagnostics only). `--allow-leaks` overrides the secret block (not recommended).
-
-**2. Connect it to your AI assistant (MCP)**
-```bash
-cd mcp && npm install && cd ..
-# Claude Code:
-claude mcp add knosky -e KC_CITY=/abs/path/city-data.json -- node /abs/path/mcp/server.mjs
-```
-Or add to your Claude Desktop / Cursor / VS Code MCP config:
-```json
-"knosky": {
-  "command": "node",
-  "args": ["/abs/path/mcp/server.mjs"],
-  "env": { "KC_CITY": "/abs/path/city-data.json" }
-}
-```
-Then ask: *"search KnoSky for what we decided about authentication."* Read-only tools exposed: `kc_search`, `kc_get_node`, `kc_list_categories`, `kc_get_provenance`, `kc_related`.
-
-**See how your code connects.** Select a file in the city to see its **connections** (roads to the files it imports / that import it) and **churn** (recently-changed files glow). Or ask your assistant *"what connects to src/auth.js?"* — file-level structure only, not code analysis.
-
-**3. Get PR navigation comments automatically (GitHub Action — PR-GPS)**
-
-Add this to any workflow that runs on pull requests:
-
-```yaml
-- name: Check out the repo (full history so the diff works)
-  uses: actions/checkout@v4
-  with:
-    fetch-depth: 0
-
-- name: KnoSky PR-GPS
-  uses: SathiaAI/knosky@v0.5.0
-  with:
-    base: ${{ github.event.pull_request.base.sha }}
-    head: ${{ github.event.pull_request.head.sha }}
-```
-
-The action posts (and updates) a single advisory comment on the PR listing which files changed, suggested review starting points, and related tests/docs. It reads file/folder/import structure only — never uploads code bodies — and **never blocks or gates the build**. The `github-token` input defaults to the workflow token; a `fail-on-secret` guard is available for stricter CI setups (see [`action.yml`](./action.yml) for all inputs).
-
----
-
-## What it is **not** (on purpose)
-- **Not a code-RAG engine.** It won't read your whole codebase and answer deep questions. It's a **map and a router** — it tells you *where* things are and hands you (or your AI) the source. (Reach for Cursor/Glean for deep code Q&A.)
-- **Not a cloud service.** No upload, no account, nothing leaves your machine. (A hosted option may come later.)
-- **Not a copy of your knowledge.** A navigable **index of pointers** — titles, headings, short excerpts that link back to the live file — never your full file contents.
-
-## Privacy & safety
-- Runs locally; your source never leaves your machine.
-- Indexes pointers + light projections (title, headings, ~200-char excerpt, tags) — **never full file bodies**.
-- Skips `.git`, `node_modules`, `secrets/`, `keys/`, `.env*`, plus your `.gitignore`/`.kcignore` (git's own ignore rules apply inside a repo).
-- Scrubs common secret/PII patterns and **fails the build closed** if a secret-like value is detected. Build with **`--share-safe`** for a safety report before sharing.
-- Generated cities embed your data as inert JSON and escape untrusted file/folder names — opening or sharing a city won't execute injected code.
-
-More: **[PRIVACY.md](./PRIVACY.md)** · **[LIMITATIONS.md](./LIMITATIONS.md)** · **[SECURITY.md](./SECURITY.md)** · **[CHANGELOG.md](./CHANGELOG.md)** · **[How KnoSky compares](./wiki/comparison.md)**
-
-## License & credits
-Free to use under the **[Functional Source License (FSL-1.1-MIT)](./LICENSE.md)** — use it freely; you just can't repackage it as a competing product. Converts to MIT two years after each release. "KnoSky" is a trademark of the author.
-
-City artwork is **[Kenney](https://kenney.nl)** (CC0 / public domain) — see [CREDITS.md](./CREDITS.md).
+# KnoSky
+
+*Your knowledge as a skyline.*
+
+**Turn any repo or folder of docs into a living, explorable city — and give your AI assistant grounded, cited answers from your own source. Runs entirely on your machine. Free.**
+
+> *Born from building [Sathia](https://sathia.ai).*
+
+---
+
+
+> **Trust model (approved wording):** KnoSky's local trust model applies the core security principles of TUF — role separation, threshold signing, survivable key compromise, and freshness-guaranteed revocation — adapted from TUF's server-oriented update distribution to a fully local, no-egress agentic environment, with attestation formats based on in-toto/DSSE.
+
+## See it in 10 seconds
+
+Open **[`demo/knosky-demo.html`](./demo/knosky-demo.html)** in your browser (just double-click it — it's a single self-contained file). That's a sample project rendered as a city. Now point it at your own.
+
+---
+
+## The problem
+Your project grows faster than anyone can hold in their head. Hundreds of files, decisions, and docs across folders. A file tree tells you what files exist — not what the *system* is. So things get lost, decisions get re-litigated, and your AI assistant confidently makes things up about your own codebase.
+
+## What you get (the outcome)
+
+> **Measured (SAT-439, 5 tasks, naive agent vs. KnoSky-guided agent):**
+> **68% fewer tokens · 70% fewer tool calls · 6× faster to the right file**
+> *(All guided runs answered correctly; the naive agent found the target in 3 of 5 tasks and answered correctly in 0.)*
+
+- **See your whole project in one screen.** Instead of scrolling a file tree, you see the *shape* of everything — which areas are big, how they connect, where the gaps are. New collaborators get oriented in minutes, not weeks.
+- **Find anything in seconds.** Search the city — or ask your assistant *"where does auth live / what did we decide about billing"* — and jump straight to the **live file**.
+- **Your AI answers from YOUR source, with citations.** Connect it to Claude / Cursor / VS Code / Gemini and your assistant stops guessing about your codebase — it cites the real file, every time.
+- **Zero setup tax, local-first by default.** Point it at a folder → a city in under a minute. Deterministic, **$0 tokens** to keep fresh, **nothing ever leaves your machine**, and a fail-closed secret scan before you share. (KnoSky does not claim "zero data risk" — see [PRIVACY.md](./PRIVACY.md).)
+
+**Net:** faster comprehension, reliable recall of your own knowledge, and a grounded AI — without giving up privacy or paying a cent.
+
+## Who it's for
+Developers, founders, and architects sitting on a sprawling repo or knowledge base who want to *understand and navigate their own work fast* — and want their AI assistant grounded in it — without uploading anything.
+
+---
+
+## How it works
+
+**Quickstart — one command:**
+```bash
+npx knosky .
+```
+Indexes the current folder, opens the city, prints the MCP config for your AI assistant (Claude Code / Claude Desktop / Cursor / VS Code) plus a few starter prompts, and starts the local connector. Point it anywhere with `npx knosky /path/to/your/repo`. Flags: `--no-open`, `--no-serve`.
+
+Prefer a clone? `git clone https://github.com/SathiaAI/knosky && cd knosky && npm install && node bin/knosky.mjs .`
+
+Want the individual pieces instead? Read on.
+
+**Requirements:** [Node.js](https://nodejs.org) 18+.
+
+**1. Build your city from a folder or repo**
+```bash
+node core/fs-indexer.mjs --root /path/to/your/repo --out city-data.json --share-safe
+node renderer/build-rich.mjs city-data.json city.html
+```
+Open `city.html`. Every top-level folder is a **district**, every file a **building**, every building links to the real source.
+
+**Flags:** `--share-safe` strips your absolute path (basename only) and prints a safety report — and the build **fails closed** if a secret-like value is detected. `--redact AcmeCorp,SecretProject` masks (and skips files matching) project-specific terms. `--include-absolute-root` keeps the full local path (private diagnostics only). `--allow-leaks` overrides the secret block (not recommended).
+
+**2. Connect it to your AI assistant (MCP)** — DEC-108 menu
+
+SSOT: [`ssot/tool-menu.json`](./ssot/tool-menu.json) · decision codes: [`ssot/decision-codes.json`](./ssot/decision-codes.json) · ladder: [`ssot/ladder-l0-l3.md`](./ssot/ladder-l0-l3.md). README = wiki = binary for tool names (AR-03).
+
+```bash
+cd mcp && npm install && cd ..
+# Claude Code (coding profile — default packs):
+claude mcp add knosky -e KC_CITY=/abs/path/city-data.json -e KC_PROFILE=coding -- node /abs/path/mcp/server.mjs
+```
+Or add to your Claude Desktop / Cursor / VS Code / Codex MCP config:
+```json
+"knosky": {
+  "command": "node",
+  "args": ["/abs/path/mcp/server.mjs"],
+  "env": {
+    "KC_CITY": "/abs/path/city-data.json",
+    "KC_PROFILE": "coding"
+  }
+}
+```
+
+| Profile (`KC_PROFILE`) | What it is for | Tools |
+| :--- | :--- | :--- |
+| **coding** (default packs) | Hermes, Claude Code, Cursor, Codex CLI, VS Code | Tier 0 map + Tier 1 governed |
+| **security** | Operators / CI verify | Coding tools + `kc_audit_query`, `kc_audit_verify` |
+| **advisory** | Explicit non-authorizing explore | Tier 0 map (+ labeled Mode A `kc_route`) |
+
+**Mode A vs Mode B (DEC-106 / DEC-108)**
+
+| Mode | Label on the wire | Meaning |
+| :--- | :--- | :--- |
+| **Mode A** | `ADVISORY_UNAUTH` | Non-authorizing map / tips. Not policy-certified, not swarm-safe. |
+| **Mode B** | `ALLOW` or `DENY_*` (+ receipt on ALLOW) | Governed: identity + policy + audit before any authorized claim. |
+
+Default coding profile uses **Mode B** for governed tools. Mode A is available via `KC_PROFILE=advisory` or `advisory=true` on dual-mode `kc_route` — always labeled; never market it as governed.
+
+**Official tool menu (freeze)**
+
+| Tier | Tools | Authorizing? |
+| :--- | :--- | :---: |
+| **Tier 0 map** | `kc_search`, `kc_get_node`, `kc_list_categories`, `kc_get_provenance`, `kc_related` | No (map only) |
+| **Tier 1 governed** | `kc_route` (**dual-mode**), `kc_bundle`, `kc_policy_check` | Yes when Mode B `ALLOW` |
+| **Security profile only** | `kc_audit_query`, `kc_audit_verify` | Audit verify — not on coding packs |
+
+- **`kc_route`** — GPS toward a destination. Mode B: `ALLOW` / `DENY_*` with audit receipt; Mode A: labeled `ADVISORY_UNAUTH` tips only.
+- **`kc_bundle`** — Share-oriented pointer / intent-manifest under the same gates + fail-closed secret scan.
+- **`kc_policy_check`** — Dry-run policy decision + reasons without preferring a full route body.
+
+**Closed decision codes** (no open strings on the wire):  
+`ALLOW` · `DENY` · `DENY_IDENTITY` · `DENY_POLICY` · `DENY_AUDIT` · `DENY_FRESHNESS` · `DENY_EVIDENCE` · `ERROR_INVALID_INPUT` · `ERROR_INDEX` · `ADVISORY_UNAUTH`
+
+Then ask: *"search KnoSky for what we decided about authentication"* or *"route me to the auth policy under Mode B."*
+
+**Guarantee ladder (honest claims — DEC-110)** — never claim higher than `knosky doctor` for this install:
+
+| L | Name | Promise |
+| :---: | :--- | :--- |
+| **L0** | Local map | Index + navigate locally; no KnoSky upload by default |
+| **L1** | Share-safe | Fail-closed secret controls before share artifacts |
+| **L2** | Governed evaluator | Mode B identity + policy + audit (or safe DENY) |
+| **L3** | Swarm domain | Multi-agent coordinator on Mode B (leases/quotas/…) |
+
+Wave 1 ships **L0–L2 paths** and an **L3 coordinator foundation** (local modules + `doctor` claim ceiling only — not “L3 ready at every install”). Do **not** treat marketing copy as “production swarm-safe at every install” until `doctor` reports `l3_ready` for that domain. Windows kernel lockdown is **unsupported/inactive** until packaging proves otherwise — see [LIMITATIONS.md](./LIMITATIONS.md).
+
+**Packs (Wave 1)** — same DEC-108 menu: P0 Hermes · Claude Code · Cursor · Codex CLI · P1 VS Code MCP · Greptile recipe · GHA PR-GPS. Audit tools stay off coding packs.
+
+**See how your code connects.** Select a file in the city to see its **connections** (roads to the files it imports / that import it) and **churn** (recently-changed files glow). Or ask your assistant *"what connects to src/auth.js?"* — file-level structure only, not code analysis.
+
+**3. Get PR navigation comments automatically (GitHub Action — PR-GPS)**
+
+Add this to any workflow that runs on pull requests:
+
+```yaml
+- name: Check out the repo (full history so the diff works)
+  uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+
+- name: KnoSky PR-GPS
+  uses: SathiaAI/knosky@v0.5.0
+  with:
+    base: ${{ github.event.pull_request.base.sha }}
+    head: ${{ github.event.pull_request.head.sha }}
+```
+
+The action posts (and updates) a single advisory comment on the PR listing which files changed, suggested review starting points, and related tests/docs. It reads file/folder/import structure only — never uploads code bodies — and **never blocks or gates the build**. The `github-token` input defaults to the workflow token; a `fail-on-secret` guard is available for stricter CI setups (see [`action.yml`](./action.yml) for all inputs).
+
+---
+
+## What it is **not** (on purpose)
+- **Not a code-RAG engine.** It won't read your whole codebase and answer deep questions. It's a **map and a router** — it tells you *where* things are and hands you (or your AI) the source. (Reach for Cursor/Glean for deep code Q&A.)
+- **Not a cloud service.** No upload, no account, nothing leaves your machine. (A hosted option may come later.)
+- **Not a copy of your knowledge.** A navigable **index of pointers** — titles, headings, short excerpts that link back to the live file — never your full file contents.
+
+## Privacy & safety
+- Runs locally; your source never leaves your machine.
+- Indexes pointers + light projections (title, headings, ~200-char excerpt, tags) — **never full file bodies**.
+- Skips `.git`, `node_modules`, `secrets/`, `keys/`, `.env*`, plus your `.gitignore`/`.kcignore` (git's own ignore rules apply inside a repo).
+- Scrubs common secret/PII patterns and **fails the build closed** if a secret-like value is detected. Build with **`--share-safe`** for a safety report before sharing.
+- Generated cities embed your data as inert JSON and escape untrusted file/folder names — opening or sharing a city won't execute injected code.
+
+More: **[PRIVACY.md](./PRIVACY.md)** · **[LIMITATIONS.md](./LIMITATIONS.md)** · **[SECURITY.md](./SECURITY.md)** · **[CHANGELOG.md](./CHANGELOG.md)** · **[How KnoSky compares](./wiki/comparison.md)**
+
+## License & credits
+Free to use under the **[Functional Source License (FSL-1.1-MIT)](./LICENSE.md)** — use it freely; you just can't repackage it as a competing product. Converts to MIT two years after each release. "KnoSky" is a trademark of the author.
+
+City artwork is **[Kenney](https://kenney.nl)** (CC0 / public domain) — see [CREDITS.md](./CREDITS.md).

package/SECURITY.md

@@ -1,46 +1,78 @@
-# Security Policy
-
-KnoSky is a **local-first** tool: it runs on your machine, indexes your own folder, and writes a self-contained city file. It does not upload your source and has no hosted backend. The security surface that matters is the **generated artifact** (the city HTML / `city-data.json`) and the local indexer/MCP.
-
-## Supported versions
-
-The latest release on the `main` branch is supported. KnoSky is pre-1.0; please run the newest version before reporting an issue.
-
-## Reporting a vulnerability
-
-Please report security issues **privately** — do not open a public issue for anything exploitable.
-
-- Preferred: GitHub **"Report a vulnerability"** (Security → Advisories) on this repository, which opens a private channel.
-- We aim to acknowledge reports within **5 business days** and to publish a fix or mitigation for confirmed issues as quickly as is practical.
-
-When reporting, please include: the version/commit, steps to reproduce, and the impact you observed. A minimal proof-of-concept (e.g., a tiny repo or `city-data.json` that triggers the issue) helps a lot.
-
-## Safe testing guidelines
-
-- Test only against repositories and folders **you own or control**.
-- Do not include real secrets or third-party personal data in proof-of-concept artifacts.
-- Do not perform testing that degrades the service for others (there is no shared service; this is a local tool).
-
-## Handling generated artifacts (for users)
-
-- A generated city embeds **file names, paths, headings, and short excerpts** — not full file bodies. Treat a generated file as you would a directory listing with snippets.
-- Build with `--share-safe` before sharing: it strips the absolute root path (basename only), runs a fail-closed secret scan, and prints a safety report. Builds **fail closed** if a secret-like value is detected (override only with `--allow-leaks`).
-- Open city files you did not generate the same way you would any untrusted HTML.
-
-## Trust model
-
-KnoSky's local trust model applies the core security principles of TUF — role separation, threshold signing, survivable key compromise, and freshness-guaranteed revocation — adapted from TUF's server-oriented update distribution to a fully local, no-egress agentic environment, with attestation formats based on in-toto/DSSE.
-
-## Known boundary conditions
-
-**N=2 key-store quorum (D-163):** when a key store holds exactly 2 non-revoked keys, the revocation quorum formula (`Math.floor(peers/2)+1`) reduces to 1, meaning the sole peer key alone can revoke the other. This is mathematically unavoidable at N=2, is an accepted limitation (not a defect), and is explicitly exercised by red-team scenario RT-KS-001 (`test/key-store-quorum-redteam.mjs`). Deployments that require real threshold protection must maintain N≥3 non-revoked keys at all times.
-
-**M=0 sole-key self-revocation (D-167):** when a key store has been reduced to exactly 1 non-revoked key (via prior legitimate revocations), `revokeKey()` allows that key to be revoked with zero approvals (`required = 0`). This is an intentional design choice — a *self-wipe*, not a third-party bypass. Requiring peer approval when no peers exist would make a compromised last key permanently irrevocable, which is a worse outcome. D-167's quorum protection is meaningful only at N≥3; this is the N=1 edge of the same quorum curve. **Caller-identity note:** `revokeKey()` does not currently authenticate the caller as the holder of the key being revoked — it authorizes the *state* (M=0), not the *caller*. `revokeKey` has no production call sites today (enforced by an automated whole-repo scan, `test/key-store-quorum-redteam.mjs`), so this is not a live exploitable path. **This is not a simple fix:** each key's raw material (`KeyEntry.raw`) lives inside the same `ks` object `revokeKey` receives, so any caller with access to `ks` already has direct read access to every key's raw material — a self-signature check bolted onto `revokeKey` today would be trivially satisfiable by any caller (they can just read `raw` and compute the expected signature themselves), providing no real security. A genuine fix requires an architectural change — key material stored somewhere the `ks`-holding caller cannot directly read (e.g. an OS keychain or a separate process boundary) — not a signature parameter added to the existing function. Tracked and scoped as such: SAT-478. Explicitly exercised by red-team scenario RT-KS-002 (`test/key-store-quorum-redteam.mjs`). Cross-reference: SAT-472 (quorum design doc comment), SAT-477, SAT-478.
-
-## Local trust boundary
-
-HWM-file integrity (the `ledger.hwm.json` high-water-mark guard introduced in SAT-443) is part of KnoSky's local trust boundary: an attacker who can delete or modify that file — or any file under KnoSky's data directory — already has local write access to the machine, which is equivalent to controlling KnoSky's own code. This is the same boundary D-164 draws for the trust root generally; no fully-local, no-egress tool can defend against an attacker with local filesystem write access without a remote or hardware anchor, which would violate KnoSky's core no-egress design principle.
-
-## Scope
-
-In scope: injection in generated artifacts, secret leakage through projections, the local MCP server, and the indexer's privacy defaults. Out of scope: issues that require an attacker to already control your machine or your repository's contents with your knowledge.
+# Security Policy
+
+KnoSky is a **local-first** tool: it runs on your machine, indexes your own folder, and writes a self-contained city file. It does not upload your source and has no hosted backend. The security surface that matters is the **generated artifact** (the city HTML / `city-data.json`) and the local indexer/MCP.
+
+## Supported versions
+
+The latest release on the `main` branch is supported. KnoSky is pre-1.0; please run the newest version before reporting an issue.
+
+## Reporting a vulnerability
+
+Please report security issues **privately** — do not open a public issue for anything exploitable.
+
+- Preferred: GitHub **"Report a vulnerability"** (Security → Advisories) on this repository, which opens a private channel.
+- We aim to acknowledge reports within **5 business days** and to publish a fix or mitigation for confirmed issues as quickly as is practical.
+
+When reporting, please include: the version/commit, steps to reproduce, and the impact you observed. A minimal proof-of-concept (e.g., a tiny repo or `city-data.json` that triggers the issue) helps a lot.
+
+## Safe testing guidelines
+
+- Test only against repositories and folders **you own or control**.
+- Do not include real secrets or third-party personal data in proof-of-concept artifacts.
+- Do not perform testing that degrades the service for others (there is no shared service; this is a local tool).
+
+## Handling generated artifacts (for users)
+
+- A generated city embeds **file names, paths, headings, and short excerpts** — not full file bodies. Treat a generated file as you would a directory listing with snippets.
+- Build with `--share-safe` before sharing: it strips the absolute root path (basename only), runs a fail-closed secret scan, and prints a safety report. Builds **fail closed** if a secret-like value is detected (override only with `--allow-leaks`).
+- Open city files you did not generate the same way you would any untrusted HTML.
+
+## Trust model
+
+KnoSky's local trust model applies the core security principles of TUF — role separation, threshold signing, survivable key compromise, and freshness-guaranteed revocation — adapted from TUF's server-oriented update distribution to a fully local, no-egress agentic environment, with attestation formats based on in-toto/DSSE.
+
+## Known boundary conditions
+
+**N=2 key-store quorum (D-163):** when a key store holds exactly 2 non-revoked keys, the revocation quorum formula (`Math.floor(peers/2)+1`) reduces to 1, meaning the sole peer key alone can revoke the other. This is mathematically unavoidable at N=2, is an accepted limitation (not a defect), and is explicitly exercised by red-team scenario RT-KS-001 (`test/key-store-quorum-redteam.mjs`). Deployments that require real threshold protection must maintain N≥3 non-revoked keys at all times.
+
+**M=0 sole-key self-revocation (D-167):** when a key store has been reduced to exactly 1 non-revoked key (via prior legitimate revocations), `revokeKey()` allows that key to be revoked with zero approvals (`required = 0`). This is an intentional design choice — a *self-wipe*, not a third-party bypass. Requiring peer approval when no peers exist would make a compromised last key permanently irrevocable, which is a worse outcome. D-167's quorum protection is meaningful only at N≥3; this is the N=1 edge of the same quorum curve. **Caller-identity note:** `revokeKey()` does not currently authenticate the caller as the holder of the key being revoked — it authorizes the *state* (M=0), not the *caller*. `revokeKey` has no production call sites today (enforced by an automated whole-repo scan, `test/key-store-quorum-redteam.mjs`), so this is not a live exploitable path. **This is not a simple fix:** each key's raw material (`KeyEntry.raw`) lives inside the same `ks` object `revokeKey` receives, so any caller with access to `ks` already has direct read access to every key's raw material — a self-signature check bolted onto `revokeKey` today would be trivially satisfiable by any caller (they can just read `raw` and compute the expected signature themselves), providing no real security. A genuine fix requires an architectural change — key material stored somewhere the `ks`-holding caller cannot directly read (e.g. an OS keychain or a separate process boundary) — not a signature parameter added to the existing function. Tracked and scoped as such: SAT-478. Explicitly exercised by red-team scenario RT-KS-002 (`test/key-store-quorum-redteam.mjs`). Cross-reference: SAT-472 (quorum design doc comment), SAT-477, SAT-478.
+
+## Local trust boundary
+
+HWM-file integrity (the `ledger.hwm.json` high-water-mark guard introduced in SAT-443) is part of KnoSky's local trust boundary: an attacker who can delete or modify that file — or any file under KnoSky's data directory — already has local write access to the machine, which is equivalent to controlling KnoSky's own code. This is the same boundary D-164 draws for the trust root generally; no fully-local, no-egress tool can defend against an attacker with local filesystem write access without a remote or hardware anchor, which would violate KnoSky's core no-egress design principle.
+
+## Opt-in org export (SAT-546)
+
+KnoSky's core tool -- everything an `npm install knosky` / `npx knosky` user
+runs (the indexer, the local MCP server, `bin/knosky.mjs`) -- is no-egress by
+default and always, with zero exceptions inside this repository.
+
+An organization that wants to also mirror its local append-only checkpoint
+(`core/append-only-checkpoint.mjs`) to storage it owns can do so via a
+**completely separate package and repository**:
+[**knosky-export-daemon**](https://github.com/SathiaAI/knosky-export-daemon).
+
+- **Separate package, separate repo, separate install.** This repository does
+  not import, require, `dependencies`-reference, or ship any part of
+  `knosky-export-daemon` -- enforced by an automated whole-repo test
+  (`test/append-only-checkpoint.test.mjs`, F02-020/F02-021: no file or
+  directory named "daemon" or matching "export-daemon" exists anywhere in
+  this repo, and `package.json` declares no dependency on it). Installing
+  `knosky` never installs it; an organization must run a second, deliberate
+  `npm install knosky-export-daemon`.
+- **Off by default, explicit config required.** The daemon does nothing
+  without a config file the org must create themselves, naming an HTTPS
+  destination **the org itself owns** -- never a Sathia/KnoSky-operated
+  endpoint. `parseExportConfig` rejects a missing, disabled, or non-HTTPS
+  config.
+- **Loud at runtime.** Starting the daemon prints an explicit warning that it
+  makes real network calls and is not part of KnoSky's no-egress core tool,
+  before doing anything else.
+- **Purpose:** the append-only local file is the guarantee; the export daemon
+  in the other repo is an optional convenience layered on top of it for an
+  org that wants an off-machine copy -- never a replacement for, or a
+  dependency of, the local checkpoint itself.
+
+## Scope
+
+In scope: injection in generated artifacts, secret leakage through projections, the local MCP server, and the indexer's privacy defaults. Out of scope: issues that require an attacker to already control your machine or your repository's contents with your knowledge.

package/action/post-comment.mjs

@@ -1,89 +1,94 @@
-#!/usr/bin/env node
-// KnoSky CI3 — GitHub Action glue (KSV2-CI3). Runs knoskyCi() to produce the
-// route/safety artifacts, renders the claims-disciplined comment body via
-// renderPrComment(), then upserts (creates or updates) ONE PR comment via the
-// GitHub REST API using the caller-supplied token.
-//
-// HARD RULE (matches ci.mjs / D-162 claims discipline): this script must NEVER
-// fail the consumer's build on an internal error. The only way this process
-// exits non-zero is `fail-on-secret: true` AND knoskyCi() actually finding a
-// secret-like pattern in the emitted artifacts — everything else is caught and
-// logged, never thrown past main().
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const CORE = path.resolve(HERE, '..', 'core');
-const MARKER = '<!-- knosky-pr-gps -->';
-
-async function ghFetch(token, url, opts = {}) {
-  const res = await fetch(url, {
-    ...opts,
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: 'application/vnd.github+json',
-      'X-GitHub-Api-Version': '2022-11-28',
-      ...(opts.headers || {}),
-    },
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => '');
-    throw new Error(`GitHub API ${opts.method || 'GET'} ${url} -> ${res.status}: ${text.slice(0, 300)}`);
-  }
-  return res.status === 204 ? null : res.json();
-}
-
-async function upsertComment({ token, repo, prNumber, body }) {
-  const base = `https://api.github.com/repos/${repo}/issues/${prNumber}/comments`;
-  const existing = await ghFetch(token, `${base}?per_page=100`);
-  const mine = Array.isArray(existing)
-    ? existing.find((c) => typeof c.body === 'string' && c.body.includes(MARKER))
-    : null;
-  if (mine) {
-    await ghFetch(token, `https://api.github.com/repos/${repo}/issues/comments/${mine.id}`, {
-      method: 'PATCH',
-      body: JSON.stringify({ body }),
-    });
-    console.log('KnoSky action: updated the existing PR-GPS comment.');
-  } else {
-    await ghFetch(token, base, { method: 'POST', body: JSON.stringify({ body }) });
-    console.log('KnoSky action: posted a new PR-GPS comment.');
-  }
-}
-
-async function main() {
-  const env = process.env;
-  const token = env.GITHUB_TOKEN;
-  const repo = env.KC_REPO || '';
-  const prNumber = env.KC_PR_NUMBER || '';
-
-  const { knoskyCi } = await import(path.join(CORE, 'ci.mjs'));
-  const { renderPrComment } = await import(path.join(CORE, 'pr-comment.mjs'));
-
-  const { exitCode, routeJson, safetyJson } = await knoskyCi({
-    root: env.KC_ROOT || '.',
-    base: env.KC_BASE,
-    head: env.KC_HEAD,
-    cityPath: env.KC_CITY,
-    failOnSecret: env.KC_FAIL_ON_SECRET === 'true',
-  });
-
-  if (!token || !repo || !prNumber) {
-    // Not a pull_request context (or the caller didn't wire the inputs) —
-    // nothing to comment on. Advisory tool, nothing to do, exit clean.
-    console.log('KnoSky action: no PR context (repo/PR number/token missing) — skipping the comment.');
-    return exitCode;
-  }
-
-  const body = MARKER + '\n' + renderPrComment({ routeJson, safetyJson });
-  await upsertComment({ token, repo, prNumber, body });
-
-  return exitCode;
-}
-
-main()
-  .then((code) => { process.exitCode = code || 0; })
-  .catch((err) => {
-    console.error('KnoSky action: internal error (advisory-only — not failing the build):', err && err.message);
-    process.exitCode = 0;
-  });
+#!/usr/bin/env node
+// KnoSky CI3 — GitHub Action glue (KSV2-CI3). Runs knoskyCi() to produce the
+// route/safety artifacts, renders the claims-disciplined comment body via
+// renderPrComment(), then upserts (creates or updates) ONE PR comment via the
+// GitHub REST API using the caller-supplied token.
+//
+// HARD RULE (matches ci.mjs / D-162 claims discipline): this script must NEVER
+// fail the consumer's build on an internal error. The only way this process
+// exits non-zero is `fail-on-secret: true` AND knoskyCi() actually finding a
+// secret-like pattern in the emitted artifacts — everything else is caught and
+// logged, never thrown past main().
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CORE = path.resolve(HERE, '..', 'core');
+const MARKER = '<!-- knosky-pr-gps -->';
+
+/** Dynamic import that works with Windows absolute paths (file:// required). */
+function importCore(name) {
+  return import(pathToFileURL(path.join(CORE, name)).href);
+}
+
+async function ghFetch(token, url, opts = {}) {
+  const res = await fetch(url, {
+    ...opts,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      ...(opts.headers || {}),
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`GitHub API ${opts.method || 'GET'} ${url} -> ${res.status}: ${text.slice(0, 300)}`);
+  }
+  return res.status === 204 ? null : res.json();
+}
+
+async function upsertComment({ token, repo, prNumber, body }) {
+  const base = `https://api.github.com/repos/${repo}/issues/${prNumber}/comments`;
+  const existing = await ghFetch(token, `${base}?per_page=100`);
+  const mine = Array.isArray(existing)
+    ? existing.find((c) => typeof c.body === 'string' && c.body.includes(MARKER))
+    : null;
+  if (mine) {
+    await ghFetch(token, `https://api.github.com/repos/${repo}/issues/comments/${mine.id}`, {
+      method: 'PATCH',
+      body: JSON.stringify({ body }),
+    });
+    console.log('KnoSky action: updated the existing PR-GPS comment.');
+  } else {
+    await ghFetch(token, base, { method: 'POST', body: JSON.stringify({ body }) });
+    console.log('KnoSky action: posted a new PR-GPS comment.');
+  }
+}
+
+async function main() {
+  const env = process.env;
+  const token = env.GITHUB_TOKEN;
+  const repo = env.KC_REPO || '';
+  const prNumber = env.KC_PR_NUMBER || '';
+
+  const { knoskyCi } = await importCore('ci.mjs');
+  const { renderPrComment } = await importCore('pr-comment.mjs');
+
+  const { exitCode, routeJson, safetyJson } = await knoskyCi({
+    root: env.KC_ROOT || '.',
+    base: env.KC_BASE,
+    head: env.KC_HEAD,
+    cityPath: env.KC_CITY,
+    failOnSecret: env.KC_FAIL_ON_SECRET === 'true',
+  });
+
+  if (!token || !repo || !prNumber) {
+    // Not a pull_request context (or the caller didn't wire the inputs) —
+    // nothing to comment on. Advisory tool, nothing to do, exit clean.
+    console.log('KnoSky action: no PR context (repo/PR number/token missing) — skipping the comment.');
+    return exitCode;
+  }
+
+  const body = MARKER + '\n' + renderPrComment({ routeJson, safetyJson });
+  await upsertComment({ token, repo, prNumber, body });
+
+  return exitCode;
+}
+
+main()
+  .then((code) => { process.exitCode = code || 0; })
+  .catch((err) => {
+    console.error('KnoSky action: internal error (advisory-only — not failing the build):', err && err.message);
+    process.exitCode = 0;
+  });