knosky 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to KnoSky. Versions are git-tagged on this repo.
+
+## [0.3.0] - 2026-06-29 — One-command launcher (npx)
+
+### Added
+- `npx knosky [path]` one-command launcher: indexes the folder, builds and opens the city, prints the MCP config (Claude Code / Claude Desktop / Cursor / VS Code) and suggested first prompts, then starts the local MCP server. Flags: `--no-open`, `--no-serve`. Reuses the verified indexer/renderer/MCP and inherits fail-closed `--share-safe` safety.
+- Root `package.json` with a `knosky` bin and a `files` allowlist for publishing.
+
+## [0.2.0] - 2026-06-29 — Security hardening + safe-share
+
+### Security
+- **Generated artifacts hardened against injection.** City data is embedded as inert JSON (`<script type="application/json">`) and the builder escapes `<` and U+2028/U+2029, so a repo containing `</script>` can no longer execute code in a generated city.
+- **Untrusted names escaped.** District/category names, file titles, and kinds render through HTML escaping; colors are validated. A folder named `<img onerror=...>` renders as harmless text, not a live element.
+- **Fail-closed secret scanning.** Expanded patterns (GitHub, OpenAI, Stripe, Google, Slack, GitLab, npm, JWT, SSH, AWS, PEM). The build now **fails closed** if a secret-like value is detected (override with `--allow-leaks`).
+- **postMessage bridge gated.** Disabled in the standalone build; only active in embedded mode with an origin allowlist.
+
+### Added
+- `--share-safe` — strips the absolute root path (basename only) and prints a safety report.
+- `--include-absolute-root` — opt back in to the full local path for private diagnostics.
+- `SECURITY.md`, `PRIVACY.md`, `LIMITATIONS.md` — disclosure path + trust docs.
+
+### Changed
+- **Privacy default:** the generated index stores the folder **basename**, not the absolute path.
+- **Ignore accuracy:** inside a git repo, git's own ignore rules are applied (`git check-ignore`); the conservative parser remains the fallback for non-git folders.
+- **MCP input caps:** `kc_search` bounds query length and result count; ids are length-capped — avoids token burn and runaway output.
+- Committed a lockfile for reproducible MCP installs.
+
+## [0.1.0] - 2026-06-27 — Initial public release
+- Local-first repo/folder → explorable isometric city (Kenney CC0 art).
+- Local stdio MCP: `kc_search`, `kc_get_node`, `kc_list_categories`, `kc_get_provenance`.
+- Single-file, self-contained city HTML. FSL-1.1-MIT license.

package/CREDITS.md

@@ -0,0 +1,14 @@
+# Credits
+
+## Artwork
+City sprites (buildings, city details, landscape tiles, vehicles) are by **Kenney** — <https://kenney.nl>.
+Licensed **CC0 1.0 Universal (public domain)**: <https://creativecommons.org/publicdomain/zero/1.0/>.
+No rights reserved; attribution appreciated but not required. The original texture atlases ship in
+`renderer/art/kenney/`.
+
+## Software
+KnoSky is released under the Functional Source License (FSL-1.1-MIT) — see [LICENSE.md](./LICENSE.md).
+
+Dependencies:
+- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) (MIT) — local MCP server.
+- [`zod`](https://github.com/colinhacks/zod) (MIT) — schema validation.

package/LICENSE.md

@@ -0,0 +1,76 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Paul Poulose / Sathia
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under these Terms and Conditions, as indicated by our inclusion of these Terms and Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents, Redistribution and Trademark clauses below, we hereby grant you the right to use, copy, modify, create derivative works, publicly perform, publicly display and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use means making the Software available to others in a commercial product or service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our patents, the license grant above includes a license under our patents. If you make a claim against any party that the Software infringes or contributes to the infringement of any patent, then your patent license to the Software ends immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of the Software. If you redistribute any copies, modifications or derivatives of the Software, you must include a copy of or a link to these Terms and Conditions and not remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of the Software, you have no right under these Terms and Conditions to use our trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under the MIT License that is effective on the second anniversary of the date we make the Software available. On or after that date, you may use the Software under the MIT License, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of the Software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+> Note (not part of the license): "KnoSky" and "Sathia" are trademarks of the Licensor. FSL gives
+> free use without allowing a competing product; it converts to MIT two years after each version's release.

package/LIMITATIONS.md

@@ -0,0 +1,23 @@
+# Known limitations
+
+KnoSky is a **map and citation layer**, not a code-intelligence engine. Being clear about the boundary keeps expectations honest.
+
+## What KnoSky is good at
+
+- Orienting you in a repo or docs folder fast: where things live, how areas connect.
+- Giving you (and your AI assistant, via the local MCP) **cited pointers** back to the real source.
+- A private, always-fresh, $0 index that runs entirely on your machine.
+
+## What KnoSky is not (yet)
+
+- **Not deep code intelligence.** It does not parse call graphs, type information, runtime dependencies, or semantic architecture. It indexes pointers and light projections, not file bodies.
+- **Not a full-text / code-RAG search.** It will not answer questions over the *contents* of your files. For deep code Q&A, your AI assistant should read the source it cites (that's what the MCP citations are for) or use a dedicated code-search tool.
+- **Not a cloud service.** No sync, no multi-user, no hosted backend.
+
+## Practical notes
+
+- **Ignore matching:** inside a git repo, git's own ignore rules are applied; outside git, a conservative `.gitignore`/`.kcignore` parser is used and may differ from git in edge cases.
+- **Large repos:** indexing is capped (default 6000 files, `--max`) to stay fast; very large monorepos may need `--max` raised or extra `.kcignore` entries.
+- **Categories:** the default categorizer uses top-level folder names. AI-suggested categories are opt-in and metadata-only.
+
+See also: [README.md](README.md), [PRIVACY.md](PRIVACY.md), [SECURITY.md](SECURITY.md).

package/PRIVACY.md

@@ -0,0 +1,30 @@
+# Privacy
+
+KnoSky is **local-first**. It runs on your machine, reads your folder, and writes files on your machine. There is no KnoSky account, no server, and no telemetry. Your source code is never uploaded by KnoSky.
+
+## What KnoSky reads
+
+To build the map, the indexer reads file and folder names and the **first ~4 KB** of text files (to pull a title, a few headings, and a one-line excerpt). It does **not** copy full file bodies.
+
+## What ends up in a generated city
+
+A generated `city-data.json` / city HTML contains **pointers and light projections**, not your code:
+
+- file paths (relative), folder/category names
+- titles, a handful of headings, and a short (<=200 char) excerpt per file
+- tags (file extensions), simple link relationships, and a source revision
+
+It does **not** contain full file contents.
+
+## Defaults that protect you
+
+- The absolute root path is **stripped to its basename** by default (use `--include-absolute-root` only for private, local diagnostics).
+- Text projections run through a **secret/PII scrubber**, and the build **fails closed** if a secret-like value is detected (override only with `--allow-leaks`).
+- `--share-safe` prints a safety report (files scanned/skipped, secrets found, risk level) before you share anything.
+- `.gitignore` and a `.kcignore` are honored; inside a git repo, git's own ignore rules are applied.
+
+## What we don't promise
+
+We do **not** claim "zero data risk." A generated city is like a directory listing with short snippets. Treat it accordingly: **review a city file (or build with `--share-safe`) before sharing it**, and open city files you did not generate the same way you'd open any untrusted HTML.
+
+See also: [SECURITY.md](SECURITY.md), [LIMITATIONS.md](LIMITATIONS.md).

package/README.md

@@ -0,0 +1,92 @@
+# 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)
+- **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, zero data risk.** Point it at a folder → a city in under a minute. Deterministic, **$0 tokens** to keep fresh, and **nothing ever leaves your machine.**
+
+**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:**
+```bash
+git clone https://github.com/SathiaAI/knosky && cd knosky && npm install
+node bin/knosky.mjs /path/to/your/repo
+```
+Indexes the 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. Flags: `--no-open`, `--no-serve`.
+
+*Coming to npm:* `npx knosky .` — the same thing in one command, no clone.
+
+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`.
+
+---
+
+## 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)**
+
+## 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

@@ -0,0 +1,32 @@
+# 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.
+
+## 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/bin/knosky.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// KnoSky one-command launcher: index a folder -> build the city -> open it ->
+// print the MCP config + first prompts -> start the local MCP server.
+// Reuses the verified core/renderer/mcp scripts as child processes (no new logic to trust).
+//
+//   npx knosky [path]            # default: current folder
+//   npx knosky . --no-open       # don't auto-open the browser
+//   npx knosky . --no-serve      # build + print config, don't start the MCP server
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '..');
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter(a => a.startsWith('--')));
+const target = path.resolve(argv.find(a => !a.startsWith('--')) || '.');
+const NODE = process.execPath;
+
+if (!fs.existsSync(target)) { console.error('KnoSky: path not found: ' + target); process.exit(1); }
+
+const outDir = path.join(target, '.knosky');
+fs.mkdirSync(outDir, { recursive: true });
+const cityJson = path.join(outDir, 'city-data.json');
+const cityHtml = path.join(outDir, 'city.html');
+
+const run = (script, args) => spawnSync(NODE, [path.join(ROOT, script), ...args], { stdio: 'inherit' });
+
+console.log('\nKnoSky -> indexing ' + target);
+let r = run('core/fs-indexer.mjs', ['--root', target, '--out', cityJson, '--share-safe']);
+if (r.status !== 0) { console.error('\nKnoSky: indexing was blocked or failed (see above). Nothing was opened.'); process.exit(r.status || 1); }
+
+r = run('renderer/build-rich.mjs', [cityJson, cityHtml]);
+if (r.status !== 0) { console.error('\nKnoSky: building the city failed.'); process.exit(1); }
+
+if (!flags.has('--no-open')) {
+  const isWin = process.platform === 'win32', isMac = process.platform === 'darwin';
+  const cmd = isWin ? 'cmd' : isMac ? 'open' : 'xdg-open';
+  const a = isWin ? ['/c', 'start', '', cityHtml] : [cityHtml];
+  try { spawn(cmd, a, { detached: true, stdio: 'ignore' }).unref(); } catch (_) {}
+}
+
+const mcpServer = path.join(ROOT, 'mcp', 'server.mjs');
+const cfg = JSON.stringify({ mcpServers: { knosky: { command: 'node', args: [mcpServer], env: { KC_CITY: cityJson } } } }, null, 2);
+
+console.log('\n  City:  ' + cityHtml);
+console.log('\nConnect your AI assistant so it answers from THIS repo, with citations.');
+console.log('Claude Code:');
+console.log('  claude mcp add knosky -e KC_CITY="' + cityJson + '" -- node "' + mcpServer + '"');
+console.log('\nClaude Desktop / Cursor / VS Code MCP config:');
+console.log(cfg.split('\n').map(l => '  ' + l).join('\n'));
+console.log('\nThen try one of these to see the loop (grounded, cited answers):');
+console.log('  - "Using KnoSky, where does authentication live in this repo?"');
+console.log('  - "Using KnoSky, what are the entry points of this project?"');
+console.log('  - "Using KnoSky, which files should I read to understand billing?"');
+
+if (flags.has('--no-serve')) {
+  console.log('\n(--no-serve) Not starting the MCP server. Run it later with:');
+  console.log('  KC_CITY="' + cityJson + '" node "' + mcpServer + '"\n');
+  process.exit(0);
+}
+
+console.log('\nStarting the local MCP server (Ctrl+C to stop)...\n');
+const mcp = spawn(NODE, [mcpServer, cityJson], { stdio: 'inherit' });
+mcp.on('exit', c => process.exit(c || 0));
+process.on('SIGINT', () => { try { mcp.kill(); } catch (_) {} process.exit(0); });

package/core/CONTRACT.md

@@ -0,0 +1,70 @@
+# Knowledge City — Data Contract v2 (the shared spine)
+
+> Phase 1a deliverable (SAT-385 → build). The one schema both faces (City + MCP) and every source
+> (fs/github/board) depend on. Generalizes the fixed-4-district v1 → **N categories**. Pointers +
+> projections ONLY — never file bodies (D-146). Council fixes baked in: a serialization **allowlist** + a
+> best-effort **denylist scrub**. Proven to represent the current live city losslessly.
+
+## Envelope
+```jsonc
+{
+  "schema_version": "2.0",
+  "generated_at": "<ISO8601>",
+  "source": { "kind": "fs|github|board|legacy", "ref": "<path/repo>", "rev": "<commit/rev>" },
+  "categories": [ { "id": "technical", "label": "Technical", "color": "#4f8cff", "order": 0 } ],
+  "node_count": 150,
+  "nodes": [ /* Node[] */ ]
+}
+```
+`categories[]` is the **N-category manifest** that replaces the hardcoded 4 districts — the renderer derives
+its districts/colors from this, so the board scales to however many categories a source has.
+
+## Node
+```jsonc
+{
+  "id": "decision:D-146",          // stable, source-derived
+  "kind": "decision|spec|file|dir|doc|...",
+  "title": "Index, not copy",      // projection
+  "summary": "<= 200 chars",       // projection (excerpt, never full body)
+  "category": "governance",        // category id (was "district")
+  "status": "locked",              // optional
+  "fact_date": "2026-06-19",       // optional
+  "tags": [],                      // optional projection
+  "headings": [],                  // optional projection (for nav/search)
+  "links": ["decision:D-147"],     // edges to other node ids
+  "provenance": { "store": "...", "ref": "...", "source_rev": "...", "fetched_at": "..." },
+  "visibility": "internal|public",
+  "sensitive": false               // scrub/flag marker
+}
+```
+Required: `id, kind, title, category, links, provenance`. Provenance required: `store, ref`.
+
+## Serialization allowlist (council fix)
+Only these node fields may **ever** be written into the index:
+`id, kind, title, summary, category, status, fact_date, tags, headings, links, provenance, visibility, sensitive`.
+The serializer drops anything else and the validator **fails** on any non-allowlisted field — this is the
+structural guard against a file `body` ever leaking into the index.
+
+## PII scrub (best-effort — NOT a security boundary)
+Applied to every emitted text projection (title/summary/headings/tags): redact emails, `key|secret|token|password|bearer` assignments, AWS access-key IDs, private-key headers → `[REDACTED]`. The indexer also skips
+`.git`, `node_modules`, `secrets/`, `keys/`, `.env*`, `dist/` by default, **plus** the repo's `.gitignore`
+and a user `.kcignore`. Honest framing (per council): this reduces accidental leakage; it is not a guarantee,
+and the local index is readable by the user's own assistant. First-run note will say so.
+
+## Projection limits
+`summary` ≤ 200 chars. No field carries a full file body. Full content is reached only by dereferencing
+`provenance` to the live source (which is what keeps the city fresh — "a map, not a copy").
+
+## Proof (this Phase-1a increment)
+Adapting the current live city (`golden/city-data.golden.json`) through `adaptLegacy()` → contract v2:
+- nodes **150 → 150** (no loss), edges **769 → 769** (no loss)
+- categories derived: `product#0, technical#1, governance#2, design#3`
+- `validateCity()` → **VALID**; scrub positive+negative tests **pass**
+- reference instance written to `golden/city-data.v2.json`
+
+Implementation: `core/contract.mjs` (schema + allowlist + scrub + validator + legacy adapter).
+Reproduce: `node core/validate-golden.mjs`.
+
+## Open at G1 (founder call)
+None on the schema itself (it's proven). Carry-forward decision (Phase 3, not blocking): the **activation
+layer** — council unanimously recommends deferring it to the monetization tier so v1 stays fully offline.

package/core/contract.mjs

@@ -0,0 +1,123 @@
+// KC city-data CONTRACT v2 — the shared spine.
+// Generalizes the fixed-4-district v1 → N categories. Pointers + projections ONLY (D-146); never bodies.
+// Council fixes baked in: serialization ALLOWLIST at the edge + best-effort DENYLIST scrub.
+
+export const SCHEMA_VERSION = '2.0';
+
+// The ONLY node fields that may ever be serialized into the index. Anything else is dropped/flagged.
+export const NODE_FIELD_ALLOWLIST = [
+  'id', 'kind', 'title', 'summary', 'category', 'status',
+  'fact_date', 'tags', 'headings', 'links', 'provenance', 'visibility', 'sensitive',
+];
+export const NODE_REQUIRED = ['id', 'kind', 'title', 'category', 'links', 'provenance'];
+export const PROVENANCE_REQUIRED = ['store', 'ref'];
+export const CATEGORY_REQUIRED = ['id', 'label', 'order'];
+export const SUMMARY_MAX = 200;
+
+// Detection patterns for the fail-closed safe-share audit (broader than the scrub list below).
+export const SECRET_PATTERNS = [
+  [/AKIA[0-9A-Z]{16}/g, 'aws-access-key'],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, 'private-key'],
+  [/\bgh[posru]_[A-Za-z0-9]{20,}\b/g, 'github-token'],
+  [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, 'github-pat'],
+  [/\bsk-[A-Za-z0-9]{20,}\b/g, 'openai-key'],
+  [/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g, 'stripe-key'],
+  [/\bAIza[0-9A-Za-z_\-]{35}\b/g, 'google-api-key'],
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, 'slack-token'],
+  [/\bglpat-[A-Za-z0-9_\-]{20,}\b/g, 'gitlab-pat'],
+  [/\bnpm_[A-Za-z0-9]{36}\b/g, 'npm-token'],
+  [/\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\b/g, 'jwt'],
+];
+export function findSecrets(text) {
+  const s = String(text); const hits = [];
+  for (const [re, kind] of SECRET_PATTERNS) { const m = s.match(re); if (m && m.length) hits.push([kind, m.length]); }
+  return hits;
+}
+
+// Best-effort secret/PII denylist applied to emitted text projections. Backed by the indexer's
+// fail-closed findSecrets() audit on the final artifact (defense in depth, not a single boundary).
+const DENY = [
+  /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,                 // emails
+  /\b(?:api[_-]?key|secret|token|password|passwd|bearer)\b\s*[:=]\s*\S+/gi,
+  ...SECRET_PATTERNS.map(([re]) => re),
+];
+// Optional project-specific sensitive terms (e.g. an employer/customer name) → redacted too.
+let EXTRA_TERMS = [];
+export function setRedactTerms(terms) {
+  EXTRA_TERMS = (terms || []).map(t => String(t).trim()).filter(Boolean)
+    .map(t => new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'gi'));
+}
+export function scrubText(s) {
+  if (typeof s !== 'string') return s;
+  let out = s;
+  for (const re of DENY) out = out.replace(re, '[REDACTED]');
+  for (const re of EXTRA_TERMS) out = out.replace(re, '[REDACTED]');
+  return out;
+}
+
+// Default path/dir ignores (the indexer also honors the repo's .gitignore + a user .kcignore).
+export const IGNORE_DEFAULTS = [
+  /(^|\/)\.git(\/|$)/, /(^|\/)node_modules(\/|$)/, /(^|\/)secrets?(\/|$)/i,
+  /(^|\/)keys?(\/|$)/i, /(^|\/)\.env/i, /(^|\/)dist(\/|$)/,
+];
+
+// Serialize one node: keep ONLY allowlisted fields, scrub text, clamp summary.
+export function serializeNode(n) {
+  const o = {};
+  for (const k of NODE_FIELD_ALLOWLIST) if (n[k] !== undefined) o[k] = n[k];
+  if (typeof o.title === 'string') o.title = scrubText(o.title);
+  if (typeof o.summary === 'string') o.summary = scrubText(o.summary).slice(0, SUMMARY_MAX);
+  if (Array.isArray(o.headings)) o.headings = o.headings.map(scrubText);
+  if (Array.isArray(o.tags)) o.tags = o.tags.map(scrubText);
+  return o;
+}
+
+// Validate a city envelope against the contract. Returns { ok, errors[] }.
+export function validateCity(city) {
+  const errors = [];
+  if (!city || typeof city !== 'object') return { ok: false, errors: ['city is not an object'] };
+  if (city.schema_version !== SCHEMA_VERSION) errors.push(`schema_version != ${SCHEMA_VERSION}`);
+  if (!Array.isArray(city.categories)) errors.push('missing categories[] manifest');
+  if (!Array.isArray(city.nodes)) errors.push('missing nodes[]');
+  const catIds = new Set((city.categories || []).map(c => c.id));
+  (city.categories || []).forEach((c, i) => {
+    for (const k of CATEGORY_REQUIRED) if (c[k] === undefined) errors.push(`category[${i}] missing ${k}`);
+  });
+  const ids = new Set();
+  (city.nodes || []).forEach((n, i) => {
+    for (const k of NODE_REQUIRED) if (n[k] === undefined) errors.push(`node[${i}] missing ${k}`);
+    if (n.category && !catIds.has(n.category)) errors.push(`node[${i}] category '${n.category}' not in manifest`);
+    if (n.id) { if (ids.has(n.id)) errors.push(`duplicate id ${n.id}`); ids.add(n.id); }
+    if (n.provenance) for (const k of PROVENANCE_REQUIRED) if (n.provenance[k] === undefined) errors.push(`node[${i}] provenance missing ${k}`);
+    if (typeof n.summary === 'string' && n.summary.length > SUMMARY_MAX) errors.push(`node[${i}] summary > ${SUMMARY_MAX}`);
+    for (const k of Object.keys(n)) if (!NODE_FIELD_ALLOWLIST.includes(k)) errors.push(`node[${i}] non-allowlisted field '${k}'`);
+  });
+  if (city.node_count !== undefined && city.node_count !== (city.nodes || []).length) errors.push('node_count mismatch');
+  return { ok: errors.length === 0, errors };
+}
+
+const PALETTE = ['#4f8cff', '#34c759', '#ff9f0a', '#af52de', '#ff375f', '#5ac8fa', '#ffd60a', '#bf5af2', '#30d158', '#ff6482'];
+
+// Build a categories[] manifest from a list of category ids (stable order + palette).
+export function deriveCategories(ids) {
+  return ids.map((id, i) => ({
+    id, label: String(id).charAt(0).toUpperCase() + String(id).slice(1),
+    color: PALETTE[i % PALETTE.length], order: i,
+  }));
+}
+
+// Legacy adapter: v1 (district, no categories[]) → v2 (category + categories[] manifest), via the allowlist.
+export function adaptLegacy(cityV1) {
+  const ids = [...new Set((cityV1.nodes || []).map(n => n.district).filter(Boolean))];
+  const categories = deriveCategories(ids);
+  const nodes = (cityV1.nodes || []).map(n => {
+    const { district, ...rest } = n;
+    return serializeNode({ ...rest, category: district });
+  });
+  return {
+    schema_version: SCHEMA_VERSION,
+    generated_at: cityV1.generated_at || new Date().toISOString(),
+    source: { kind: 'legacy', ref: cityV1.source_rev || 'unknown', rev: cityV1.source_rev || 'unknown' },
+    categories, node_count: nodes.length, nodes,
+  };
+}