{"_id":"@codemeall/harness-wiki","_rev":"4-7356d5e8a77a8d9f2115d356ff8f5462","name":"@codemeall/harness-wiki","dist-tags":{"latest":"0.3.2"},"versions":{"0.1.0":{"name":"@codemeall/harness-wiki","version":"0.1.0","license":"MIT","_id":"@codemeall/harness-wiki@0.1.0","maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"bin":{"harness-wiki":"dist/cli.js"},"dist":{"shasum":"7c4307e743b460887054b62149501af79d1777d0","tarball":"https://registry.npmjs.org/@codemeall/harness-wiki/-/harness-wiki-0.1.0.tgz","fileCount":18,"integrity":"sha512-mGMBk6Jtt7AZPZYZ1R0WsxXZYhApH9wTlylUAQLBJAMIgzVQLsUt4R/w9h3c9h/Vv5xfLY6ZAWn+d82AL5SLDA==","signatures":[{"sig":"MEYCIQCbjb5aZtVwE83vtVbP4jtf4PyAv8e4tdSRm8+7ZFHkTQIhAKuqt8EUSNQCXRpKVdte/hA5R/0xoaSqXnEuQspJHRYM","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66064},"type":"module","engines":{"node":">=20"},"gitHead":"a73539bc8d903f9aae8b3119af41b6f613f24a78","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"codemeall","email":"mdab.aziz01@gmail.com"},"_npmVersion":"10.9.8","description":"Skill-first tooling to scaffold and maintain an LLM Wiki — an agent-maintained markdown knowledge vault.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.4","typescript":"^5.8.3","@types/node":"^22.15.29"},"_npmOperationalInternal":{"tmp":"tmp/harness-wiki_0.1.0_1781005924693_0.668500394644677","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@codemeall/harness-wiki","version":"0.1.1","license":"MIT","_id":"@codemeall/harness-wiki@0.1.1","maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"bin":{"harness-wiki":"dist/cli.js"},"dist":{"shasum":"b7ff9b7b4c767b5808105cd36ae0fbdda815352c","tarball":"https://registry.npmjs.org/@codemeall/harness-wiki/-/harness-wiki-0.1.1.tgz","fileCount":21,"integrity":"sha512-nLmoXMXaXE9dcedpdX2PHOpYEgX23CbglOlv7XVdXjbuqTB72SbRsSPdC5gBgMrDom89fHxObVnVBo1l7iZ77w==","signatures":[{"sig":"MEQCICxKAxugegCy9lidZtUzUutuckGJRfBntfbfHyfvDPCVAiB68s+ZF0dBfv3TImzWcD2nWmIRWLpVlbY0nF6CV8ouRg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":75472},"type":"module","engines":{"node":">=20"},"gitHead":"dcf776e1e8ca85b60b24c02a4ac557abd16f2d0f","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"codemeall","email":"mdab.aziz01@gmail.com"},"_npmVersion":"10.9.8","description":"Skill-first tooling to scaffold and maintain an LLM Wiki — an agent-maintained markdown knowledge vault.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.4","typescript":"^5.8.3","@types/node":"^22.15.29"},"_npmOperationalInternal":{"tmp":"tmp/harness-wiki_0.1.1_1781009284859_0.353157804065134","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@codemeall/harness-wiki","version":"0.3.1","license":"MIT","_id":"@codemeall/harness-wiki@0.3.1","maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"bin":{"harness-wiki":"dist/cli.js"},"dist":{"shasum":"e403df80c1fc3cd0acf18cd2e8eeb70e02a4015d","tarball":"https://registry.npmjs.org/@codemeall/harness-wiki/-/harness-wiki-0.3.1.tgz","fileCount":22,"integrity":"sha512-E6oIyv45IYaun1SWo4sCC5t/EYCNgqon0M+SRWo5qsPOoifwCeURWYtVNfCI+1FJyvRMNyapqHJeD2rbPsoIqA==","signatures":[{"sig":"MEQCIDAFas2TkPDI1D3onWyd1lYSyrDWLV3S47fxtX04VbEIAiBKscLQxOMFfxwP+rxoBDfmvEkefeUKArIALYZj/JwfQg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":133929},"type":"module","engines":{"node":">=20"},"gitHead":"3144eedba3a6aeef4975dc80cf75b846bb0583ce","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"codemeall","email":"mdab.aziz01@gmail.com"},"_npmVersion":"10.9.8","description":"Skill-first tooling to scaffold and maintain an LLM Wiki — an agent-maintained markdown knowledge vault.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.4","typescript":"^5.8.3","@types/node":"^22.15.29"},"_npmOperationalInternal":{"tmp":"tmp/harness-wiki_0.3.1_1781013362646_0.2666621140817711","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@codemeall/harness-wiki","version":"0.3.2","description":"Skill-first tooling to scaffold and maintain an LLM Wiki — an agent-maintained markdown knowledge vault.","type":"module","bin":{"harness-wiki":"dist/cli.js"},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","typecheck":"tsc -p tsconfig.json --noEmit"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.15.29","typescript":"^5.8.3","vitest":"^3.1.4"},"engines":{"node":">=20"},"license":"MIT","_id":"@codemeall/harness-wiki@0.3.2","gitHead":"8d0827db939508c27ef9db0f958124120c15aa98","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-x5kK8+5f0L9GRgSx6UyJblc9xuEtci20jmp1j3QFak3vNCOpPiqQDyU9ySu5QJa6VDYJkyc84Ed+Ra1lhNfYXQ==","shasum":"6c49a517e7d7eca98d6afe2a19271ea270891e60","tarball":"https://registry.npmjs.org/@codemeall/harness-wiki/-/harness-wiki-0.3.2.tgz","fileCount":22,"unpackedSize":137623,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHFA7YN4bXkeMRQR/nvnrigOc0Zyyc9G3/os4R+V/iQCAiEAhw1X6+Hc9W6Ad038ikdFuKaPWfp1IkOqPovJPQ+4eMs="}]},"_npmUser":{"name":"codemeall","email":"mdab.aziz01@gmail.com"},"directories":{},"maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/harness-wiki_0.3.2_1781014361253_0.5263960972671755"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-09T11:52:04.500Z","modified":"2026-06-09T14:12:41.519Z","0.1.0":"2026-06-09T11:52:04.837Z","0.1.1":"2026-06-09T12:48:05.059Z","0.3.1":"2026-06-09T13:56:02.805Z","0.3.2":"2026-06-09T14:12:41.417Z"},"license":"MIT","description":"Skill-first tooling to scaffold and maintain an LLM Wiki — an agent-maintained markdown knowledge vault.","maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"readme":"# Harness Wiki\n\n**Skill-first tooling to scaffold and maintain an _LLM Wiki_ — a long-lived, agent-maintained markdown knowledge vault.**\n\nYou curate sources and ask questions; the agent summarizes, cross-references, files, flags contradictions, and keeps an index and log current. Unlike file-upload RAG, an LLM Wiki compiles knowledge into durable, interlinked pages instead of retrieving chunks from scratch on every query.\n\n> Based on Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) concept — see [Credits](#credits).\n\n> **Companion product.** [`@codemeall/harness-bridge`](https://github.com/codemeall/harness-bridge) tracks the **current in-flight task** in one repo via `.harness/bridge.md`. Harness Wiki tracks the **durable knowledge** around many tasks — research, design rationale, decisions. Use them together: wiki for the *why*, project repos for the *what*, bridge files for the *current work*.\n\n## Quickstart\n\nIn any agent that can load a skill (Claude Code, Codex, …), open the folder you want to become your knowledge base and say:\n\n```text\nUse the Harness Wiki skill to initialize an LLM Wiki vault here. Name: knowledge. Domain: <your topic>.\n```\n\nThen just work with it in plain language:\n\n1. **Feed it** — drop a file into `raw/`, then say `ingest raw/<file>` (or `ingest <url>`).\n2. **Ask it** — ask any question; the agent answers from the wiki with citations.\n3. **Maintain it** — say `lint` for a periodic health check.\n\nThat's the whole loop. You curate and ask; the agent does the summarizing, cross-referencing, and filing. **Want to see the output before installing anything?** Browse [`examples/knowledge-vault/`](./examples/) — a small, complete vault.\n\n## The wedge: wiki ↔ repo ↔ bridge\n\nNotes apps store text; Harness Wiki stores *decisions and the work they feed*. A vault registers the sibling project repos it serves (`vault_link`), so design rationale connects to implementation: the **wiki holds the why**, the **project repo holds the what**, and [`harness-bridge`](https://github.com/codemeall/harness-bridge) holds the **current work**. When a synthesis is approved, it hands off to the paired repo for implementation — and substantive decisions made there flow back into the vault. `vault_doctor` keeps the structure honest: stale source pages (the raw file changed since you ingested it) and broken project links get flagged on every health check.\n\n## What you get\n\n`harness-wiki` gives agents a portable skill for the full vault lifecycle. MCP and CLI commands are optional accelerators for deterministic scaffold/status operations; the actual ingest/query/lint operations are agent-driven, guided by the skill and the schema written into `CLAUDE.md` / `AGENTS.md`.\n\n```\nraw/                       # immutable source documents you curate (assets in raw/assets/)\nwiki/entities/             # people, orgs, products, places — one page each\nwiki/concepts/             # ideas, frameworks, methods, patterns\nwiki/sources/              # one summary page per ingested raw source\nwiki/syntheses/            # comparisons, analyses, decisions worth keeping\nwiki/index.md              # catalog of every page\nwiki/log.md                # append-only operations log\nCLAUDE.md / AGENTS.md      # the agent schema (carries the vault marker)\n```\n\n## Installation\n\nInstall the packaged skill into your agent's skills directory with one command — no global install, no manual file copying:\n\n```bash\nnpx -y @codemeall/harness-wiki skill-install claude          # Claude Code (~/.claude/skills)\nnpx -y @codemeall/harness-wiki skill-install claude-project  # this project's ./.claude/skills\nnpx -y @codemeall/harness-wiki skill-install codex           # Codex (~/.codex/skills)\nnpx -y @codemeall/harness-wiki skill-install --target <dir>  # any custom skills directory\n```\n\n| Preset | Installs to |\n|---|---|\n| `claude` | `~/.claude/skills` (Claude Code, personal) |\n| `claude-project` | `./.claude/skills` (Claude Code, this project) |\n| `codex` | `~/.codex/skills` (Codex, personal) |\n| `agents` | `~/.agents/skills` (generic agents, personal) |\n| `local` | `./.agents/skills` (generic agents, this project) |\n\nOnce installed, open the folder you want to become a vault and tell your agent: *\"Use the Harness Wiki skill to initialize an LLM Wiki vault here.\"*\n\nFor MCP-capable agents, also run the server (no install):\n\n```bash\nnpx -y @codemeall/harness-wiki mcp\n```\n\nFor direct terminal setup without installing globally:\n\n```bash\nnpx -y @codemeall/harness-wiki vault-init --name \"knowledge\" --domain \"software project\"\nnpx -y @codemeall/harness-wiki vault-status\n```\n\nOr install globally for the CLI:\n\n```bash\nnpm install -g @codemeall/harness-wiki\n```\n\nFrom a Git checkout:\n\n```bash\ngit clone https://github.com/codemeall/harness-wiki.git\ncd harness-wiki\nnpm install\nnpm run build\n```\n\nRequires Node.js >= 20.\n\n## Usage\n\n### Skill-first usage\n\nLoad [`skills/harness-wiki/SKILL.md`](./skills/harness-wiki/SKILL.md) into your agent or harness, then open the directory you want to become a vault and say:\n\n```text\nUse the Harness Wiki skill to initialize an LLM Wiki vault here.\nName: \"knowledge\"\nDomain: software project\n```\n\nThe skill covers initialization, ingest, query, lint, paired projects, and schema maintenance. Once the vault exists, the generated `CLAUDE.md` / `AGENTS.md` schema becomes the local operating contract.\n\n**Codex-style skills:** install or copy `skills/harness-wiki/SKILL.md` into your skills directory, then ask Codex to use the Harness Wiki skill in the vault directory.\n\nYou can install the packaged skill with the CLI:\n\n```bash\nnpx -y @codemeall/harness-wiki skill-install claude\nnpx -y @codemeall/harness-wiki skill-install claude-project\nnpx -y @codemeall/harness-wiki skill-install codex\nnpx -y @codemeall/harness-wiki skill-install agents\nnpx -y @codemeall/harness-wiki skill-install local\n```\n\nUse `--target <skillsDir>` for a custom harness skills directory:\n\n```bash\nnpx -y @codemeall/harness-wiki skill-install --target ./.agents/skills\n```\n\n**Claude-style project instructions:** add the skill text to project instructions or paste it at the start of the session. After initialization, Claude should follow the generated `CLAUDE.md`.\n\n**ChatGPT/custom harnesses:** load the skill as the system/developer instruction or first user message for the session. If your harness supports local tools, expose MCP as described below.\n\n**Generic agents:** paste the skill text, then point the agent at the target directory. The skill includes the manual non-MCP setup path.\n\n### MCP accelerator\n\nRegister Harness Wiki as an MCP server when your agent supports MCP. The skill will use MCP for deterministic scaffold/status operations. Example MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"harness-wiki\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@codemeall/harness-wiki\", \"mcp\"]\n    }\n  }\n}\n```\n\nFrom a local build, point at the built CLI instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"harness-wiki\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/harness-wiki/dist/cli.js\", \"mcp\"]\n    }\n  }\n}\n```\n\nThen open the directory you want to become a vault and tell the agent:\n\n```text\nUse the Harness Wiki skill to initialize an LLM Wiki vault here.\nName: \"knowledge\"\nDomain: software project\n```\n\nWhen calling MCP tools, the agent should pass the target workspace absolute path as `cwd`. This avoids initializing the MCP server launch directory instead of the project directory.\n\n**MCP tools**\n\n| Tool | Purpose |\n|---|---|\n| `vault_init` | Scaffold the vault at optional `cwd`: creates `raw/`, `wiki/{entities,concepts,sources,syntheses}/`, `CLAUDE.md`, `AGENTS.md`, `wiki/index.md`, `wiki/log.md`. Auto-detects empty dir (standalone vault) vs. existing project (appends a marker-fenced `<!-- harness-wiki:vault-schema -->` block to the host `CLAUDE.md` / `AGENTS.md` without touching other content). Idempotent on re-run via the marker. |\n| `vault_status` | Report scaffold state at optional `cwd` and list files in `raw/` with no matching `wiki/sources/<slug>.md` (pending ingests). Filename/slug matching is normalized, so `PRD Checkout V2.pdf` pairs with `prd-checkout-v2.md`. |\n| `vault_doctor` | Deterministic structural health check: pages missing YAML frontmatter, dead `[[wikilinks]]`, orphan pages with no inbound links, and pages absent from `wiki/index.md`. The mechanical first pass of a `lint`. |\n| `vault_search` | Plain-text search across all `wiki/` pages (case-insensitive), returning file + line + matching text. For locating relevant pages in a large vault before answering a query. |\n| `vault_stamp` | Record `source_file` + `source_sha256` into source-page frontmatter so `vault_doctor` can detect when a raw source file changes (a stale page). Run after each ingest; re-run to acknowledge a re-review. |\n| `vault_link` | Register a sibling project in the Paired-projects table and write a marker-fenced back-pointer into that repo's `CLAUDE.md`. The wiki↔repo wedge — discoverable from both sides, idempotent. |\n\n**MCP prompt:** `wiki_init_prompt` returns the canonical setup/operations prompt (also available as the resource `harness-wiki://prompts/vault-init.md`).\n\n### CLI\n\n```bash\nharness-wiki mcp                                              # run the MCP server (stdio)\nharness-wiki vault-init --name \"knowledge\" --domain \"software project\" [--cwd <path>] [--force]\nharness-wiki vault-status [--cwd <path>]\nharness-wiki vault-doctor [--cwd <path>]                      # structural health check\nharness-wiki vault-search \"<query>\" [--cwd <path>] [--limit <n>]\nharness-wiki vault-stamp [--cwd <path>]                       # record source hashes for staleness\nharness-wiki vault-link --name <n> --path <p> --purpose <text> --status <text> [--cwd <path>]\nharness-wiki skill-install <codex|agents|local> [--force]\nharness-wiki skill-install --target <skillsDir> [--force]\n```\n\nFrom a Git checkout, substitute `node /absolute/path/to/harness-wiki/dist/cli.js` for `harness-wiki`.\n\n`harness-wiki mcp` is a stdio server command. It looks idle when run directly because it is waiting for an MCP client; configure it in your agent instead of using it as an interactive command.\n\n### Prompt fallback\n\nIf your agent cannot load skills, paste [`prompts/vault-init.md`](./prompts/vault-init.md) as the first message in the directory that should become the vault, and answer the agent's domain questions.\n\n## Documentation\n\n- [`docs/llm-wiki.md`](./docs/llm-wiki.md) — full setup, daily ingest/query/lint workflow, and when to use the wiki vs. a project repo.\n- [`docs/example-feature-workflow.md`](./docs/example-feature-workflow.md) — a worked flow: tracking features, a pending list, moving items to done, reopening them, and asking about a feature's options.\n\n## Credits\n\nThe LLM Wiki pattern this tool implements was described by **Andrej Karpathy** in his [LLM Wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — an idea file meant to be handed to an LLM agent, which then builds out the specifics with you. Harness Wiki packages that pattern as a portable skill, MCP server, and CLI so it's repeatable across agents and projects. Credit for the underlying concept is his; this repository is an independent implementation.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}