{
  "markdown": "# okforge — Open Knowledge Format bundle skill\n\nA Claude Code skill for maintaining a repository's [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)\n(OKF) knowledge bundle under `.okf/`, usable in any repository.\n\nOKF is an open, human- and agent-friendly format for **knowledge** — the\nmetadata, context, and curated insight that surrounds a system. A bundle is a\ndirectory of plain markdown files: each concept document carries YAML frontmatter\nwith a required `type`, and reserved `index.md` / `log.md` files provide listings\nand history. If you can `cat` a file you can read OKF; if you can `git clone` a\nrepo you can ship it.\n\nThe skill prose lives in [`dotclaude_folder/skills/`](dotclaude_folder/skills) (each\n`SKILL.md` is an instruction file Claude loads, shipped as data and copied into a\ntarget's `.claude/` by `okforge install`); its deterministic mechanics live in\n[`src/`](src) as a small TypeScript CLI. The model writes the prose; the CLI\nanswers \"what is each folder derived from?\" and \"is the bundle still well-formed?\".\n\n## Blog series\n\nTwo short series on okforge — what it does, and the thinking behind it.\n\n**Workflow — a five-step walkthrough, from install to payoff:**\n\n1. [Your Repo Can Document Itself in One Command](docs/blog_posts/01-document-itself-one-command.blog_post.md)\n2. [Documentation Is a Derived Artifact. Configure It Like One.](docs/blog_posts/02-derived-artifact-configure-it.blog_post.md)\n3. [The Best Doc Reminder Fires Once and Shuts Up](docs/blog_posts/03-reminder-fires-once.blog_post.md)\n4. [Make \"Are the Docs Current\" a CI Check, Not a Vibe](docs/blog_posts/04-docs-current-ci-check.blog_post.md)\n5. [Markdown in Git Beats a Vector Database for Your Own System's Knowledge](docs/blog_posts/05-markdown-git-beats-vector-db.blog_post.md)\n\n**Principles — the why and how behind the design:**\n\n- [The Most Dangerous Documentation Is the Kind You Don't Trust](docs/blog_posts/20-documentation-you-dont-trust.blog_post.md)\n- [Don't Ask a Model What Code Can Compute](docs/blog_posts/21-dont-ask-a-model-what-code-can-compute.blog_post.md)\n- [AI Can Recover What Your Code Does. It Can't Recover Why.](docs/blog_posts/22-ai-cant-recover-why.blog_post.md)\n- [Your Agent's Knowledge Base Is Probably Overengineered](docs/blog_posts/23-knowledge-base-overengineered.blog_post.md)\n- [I Shipped a Dev Tool in Two Days. The Code Was the Easy Part.](docs/blog_posts/24-shipped-in-two-days.blog_post.md)\n\n## How to install\n\nRun `install` from the root of the repository you want to add OKF to (Node >=\n20.12, no install step — `npx` fetches it):\n\n```bash\nnpx okforge install .claude\n```\n\nWhen the destination folder is named `.claude`, this drops the skill prose into\n`.claude/skills/` **and** registers the `npx okforge nudge` Stop hook in\n`.claude/settings.json` (idempotent and non-destructive — existing settings and\nhooks are preserved). For any other destination it copies the skills only and\nleaves `settings.json` untouched.\n\nThen write an `.okforge.config.json` at the project root describing that repo's\nfolder-to-source mapping (see [`.okforge.config.json`](#usable-in-any-repository-okforgeconfigjson)\nbelow), and ask Claude to \"set up okf\" — or run `/okforge-maintain` — to scaffold the bundle.\n\n## Why a skill\n\nThe `.okf/` bundle is **derived** from source — each folder is generated from\nspecific files, so when those files change the docs drift. The hard parts to keep\nconsistent are the OKF format, the folder-to-source mapping, and link integrity.\nThe skill keeps those uniform so you can focus on accurate prose.\n\n## What it does\n\nThree modes, chosen from how you ask:\n\n| You say | Mode | What happens |\n|---|---|---|\n| \"set up okf\", \"create an OKF bundle\", bundle missing | **scaffold** | Creates `.okforge.config.json`, `.okf/index.md` (root, with `okf_version`), `.okf/log.md`, the folders from the mapping, and refreshes each. |\n| \"the API changed, update okf\", \"refresh okf for X\", \"update the OKF docs\" | **refresh** | Reads the current source for the affected folder(s) and regenerates only the docs whose source actually changed, grounded in what it read. |\n| \"check okf\", \"is the bundle conformant\", \"any dead links\" | **check** | Runs the conformance and dead-link lint. |\n\nInvoke it by asking Claude in plain language, or with `/okforge-maintain`. Regeneration is\nmodel-driven, so refresh is a **draft-then-review** loop: the skill rewrites the\naffected docs, you review them, then commit. It will not silently rewrite docs\nwhose source did not change.\n\n## Automatic capture going forward\n\nA companion `Stop` hook, `npx okforge nudge` (registered in\n`.claude/settings.json`), reminds you when a session changed source that an OKF\nfolder documents but left `.okf/` untouched. It is deliberately gentle:\nnon-blocking, at most once per session, and silent if you already touched `.okf/`\nthat session. It reads the same mapping the skill uses (via `npx okforge stale`),\nso the skill and the nudge never diverge.\n\n## Where the bundle lives\n\nThe bundle is the `.okf/` directory at the repository root — a valid OKF bundle is\njust a subdirectory of a larger repo, so there is no build step or manifest beyond\n`okf_version` in the root `.okf/index.md`. The folder-to-source mapping lives next\nto it in `.okforge.config.json` at the project root.\n\n## Usable in any repository: `.okforge.config.json`\n\nokforge ships with **no** repository-specific paths. Each repo declares its own\nfolder-to-source mapping in `.okforge.config.json` at the project root:\n\n```json\n{\n  \"folders\": {\n    \"runtime_concepts\": [\"packages/foo/src/model/\", \"packages/foo/src/event/\"],\n    \"config_formats\": [\"packages/foo/data/schemas/thing.schema.json\"]\n  }\n}\n```\n\nEach key is an OKF concept folder; each value is the list of source path prefixes\nthat folder is derived from. With no config present, `map`/`folders` are empty and\n`stale` is a no-op; `check` still works, since it lints the bundle's markdown\nalone. This is the only project-specific part — both the skill and the nudge read\nit from here.\n\n## The `okforge` CLI\n\nThe bundled [`okforge`](https://www.npmjs.com/package/okforge) CLI owns the\ndeterministic mechanics, run with `npx` (Node >= 20.12). `<dir>` defaults to the\ncurrent directory (the repository root).\n\n| Command | Purpose |\n|---|---|\n| `okforge map [<dir>]` | Print the full folder-to-source mapping. |\n| `okforge folders [<dir>]` | List the OKF concept folders. |\n| `okforge sources <folder> [<dir>]` | Print the source paths a folder is derived from. |\n| `okforge stale [<dir>]` | List folders whose source changed since HEAD while the folder was not edited. |\n| `okforge check [<dir>]` | Conformance + dead-link lint; exits non-zero on problems. |\n| `okforge graph <op> [args] [--bundle <dir>]` | Read-only concept-graph queries over a bundle (`overview`, `concept`, `neighbors`, `orphans`, `broken`, `path`), as JSON; powers the `okforge-query` skill. |\n| `okforge webview generate [<bundle>] [-o <dir>]` | Bake a bundle into a dependency-free static site. `<bundle>` may be a local dir or an http(s)/GitHub URL (default `.okf`). |\n| `okforge webview show [<bundle>]` | Generate the site into a temp dir and serve it over HTTP until interrupted. |\n| `okforge nudge` | Stop-hook entry: read the hook payload on stdin and maybe remind. |\n| `okforge install [<agent_folder>]` | Copy the bundled okf skill into an agent folder (default `.`); when that folder is named `.claude`, also register the `nudge` Stop hook in its `settings.json`. |\n\n`check` verifies: snake_case names only, every non-index `.md` has a non-empty\nfrontmatter `type`, sub-folder `index.md` files carry no frontmatter, and every\nbundle-relative `.md` link resolves.\n\n## Development\n\n```bash\nnpm install\nnpm run okforge -- <command>   # run the CLI from source via tsx\nnpm run typecheck              # tsc --noEmit\nnpm run build                  # compile to dist/ and copy the webview template\nnpm run symlink:dotclaude      # mirror dotclaude_folder/ into .claude/ as symlinks\nnpm run webview:open           # build the .okf webview and open it (also :build / :deploy)\n```\n\nYou can also run the source directly with `npx tsx src/cli.ts <command>`.\n\n`symlink:dotclaude` makes okforge dogfood its own skills: it links each file under\n`dotclaude_folder/` into `.claude/` with a relative symlink, so the `okforge-maintain`\nand `okforge-query` skills are live in this repo while their tracked source stays in\n`dotclaude_folder/`. It is idempotent and never overwrites a real file (e.g.\n`.claude/settings.json`).\n\n## Layout\n\n```\nsrc/                        the okforge CLI (mechanics)\n├── cli.ts                  Commander entry; wires the subcommands below\n├── misc/\n│   ├── okf_store.ts        mapping load, stale detection, conformance lint\n│   ├── okf_graph.ts        read-only concept-graph model (links, neighbors, orphans, paths)\n│   └── okf_fetch.ts        download a remote bundle by crawling its markdown links\n├── webview/\n│   ├── template/           static browser app baked into every generated site\n│   └── README.md           webview generate/show/deploy docs\n└── commands/\n    ├── map_command.ts      print the folder-to-source mapping\n    ├── folders_command.ts  list the concept folders\n    ├── sources_command.ts  print a folder's source paths\n    ├── stale_command.ts    folders whose source changed since HEAD\n    ├── check_command.ts    conformance + dead-link lint\n    ├── graph_command.ts    concept-graph queries for the okforge-query skill\n    ├── webview_command.ts  generate/serve the static webview\n    ├── nudge_command.ts    the Stop-hook nudge\n    └── install_command.ts  copy the skills into a target agent folder\ndotclaude_folder/           data shipped to a target's .claude/ by `okforge install`\n└── skills/\n    ├── okforge-maintain/\n    │   └── SKILL.md        maintain the bundle (scaffold / refresh / check)\n    └── okforge-query/\n        ├── SKILL.md        read-only browser for any OKF bundle\n        └── references/okf-rules.md   OKF v0.1 rules the browser encodes\nscripts/\n└── webview_deploy.sh       force-push webview_dist/ to the gh-pages branch\n```\n\n## Conventions\n\n- File and folder names are snake_case. No kebab-case, no spaces.\n- Every non-index `.md` is a concept document: YAML frontmatter with a non-empty\n  `type`, then structural markdown (headings, lists, tables, code) using the\n  conventional `# Schema` / `# Examples` / `# Citations` sections where they apply.\n- `index.md` is reserved and carries no frontmatter — except the root\n  `.okf/index.md`, which declares `okf_version: \"0.1\"` and `type: Bundle Index`.\n- Cross-link concepts with relative markdown paths from the doc\n  (`../runtime_concepts/job_store.md`, `./sibling.md`) — not bundle-root absolute\n  paths; cite real source files with repo-relative paths (`../../packages/...`).\n- Ground every claim in real source. Do not invent fields, routes, flags, or\n  states; if uncertain, omit.\n\n## License\n\nMIT © Jerome Etienne\n",
  "bytes": 11018,
  "sha": "c5627c0b1f817bcd05dee0796e8e94d799249eaa0cd06eff01ff406cff3145de",
  "repo_slug": "jeromeetienne/okforge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_jeromeetienne_okforge_okf_index_md_7a1697cb/readme"
}