okforge 1.0.1

package/.claude/skills/okf/README.md

@@ -0,0 +1,141 @@
+# okf — Open Knowledge Format bundle skill
+
+A Claude Code skill for maintaining the repository's Open Knowledge Format (OKF)
+knowledge bundle under `okf/`. Spec:
+https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+
+OKF is an open, human- and agent-friendly format for **knowledge** — the
+metadata, context, and curated insight that surrounds a system. A bundle is a
+directory of plain markdown files: each concept document carries YAML
+frontmatter with a required `type`, and reserved `index.md` / `log.md` files
+provide listings and history. If you can `cat` a file you can read OKF; if you
+can `git clone` a repo you can ship it.
+
+This directory holds the skill. `SKILL.md` is the instruction file Claude loads;
+this README is for humans browsing the repository.
+
+## Why a skill
+
+The `okf/` bundle is **derived** from source — each folder is generated from
+specific files, so when those files change the docs drift. The hard parts to
+keep consistent are the OKF format, the folder-to-source mapping, and link
+integrity. The skill keeps those uniform so you can focus on accurate prose.
+
+## What it does
+
+Three modes, chosen from how you ask:
+
+| You say | Mode | What happens |
+|---|---|---|
+| "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. |
+| "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. |
+| "check okf", "is the bundle conformant", "any dead links" | **check** | Runs the conformance and dead-link lint. |
+
+Invoke it by asking Claude in plain language, or with `/okf`.
+
+Regeneration is model-driven, so refresh is a **draft-then-review** loop: the
+skill rewrites the affected docs, you review them, then commit. It will not
+silently rewrite docs whose source did not change.
+
+## Automatic capture going forward
+
+A companion `Stop` hook, `npx okforge nudge` (registered in
+`.claude/settings.json`), reminds you when a session changed source that an OKF
+folder documents but left `okf/` untouched. It is deliberately gentle:
+non-blocking, at most once per session, and silent if you already touched
+`okf/` that session. It reads the same mapping the skill uses (via
+`npx okforge stale`), so the skill and the nudge never diverge.
+
+## Where the bundle lives
+
+The bundle is the `okf/` directory at the repository root — a valid OKF bundle
+is just a subdirectory of a larger repo, so there is no build step or manifest
+beyond `okf_version` in the root `okf/index.md`. The folder-to-source mapping
+lives next to it in `.okforge.config.json` at the project root.
+
+## The `okforge` CLI
+
+The bundled [`okforge`](https://www.npmjs.com/package/okforge) CLI owns the
+deterministic mechanics, run with `npx` (Node >= 20.12). The model writes the
+prose; the CLI answers "what is each folder derived from?" and "is the bundle
+still well-formed?".
+
+| Command | Purpose |
+|---|---|
+| `npx okforge map [<dir>]` | Print the full folder-to-source mapping. |
+| `npx okforge folders [<dir>]` | List the OKF concept folders. |
+| `npx okforge sources <folder> [<dir>]` | Print the source paths a folder is derived from. |
+| `npx okforge stale [<dir>]` | List folders whose source changed since HEAD while the folder itself was not edited. |
+| `npx okforge check [<dir>]` | Conformance + dead-link lint; exits non-zero on problems. |
+| `npx okforge nudge` | Stop-hook entry: read the hook payload on stdin and maybe remind. |
+
+`<dir>` defaults to the current directory (the repository root). `check` verifies:
+snake_case names only, every non-index `.md` has a non-empty frontmatter `type`,
+sub-folder `index.md` files carry no frontmatter, and every bundle-relative `.md`
+link resolves.
+
+When developing in this repo you can run the source directly with
+`npx tsx src/cli.ts <command>`, or via the npm script `npm run okforge -- <command>`.
+
+## The mapping: `.okforge.config.json`
+
+okforge ships with **no** repository-specific paths. Each repo declares its own
+folder-to-source mapping in `.okforge.config.json` at the project root:
+
+```json
+{
+  "folders": {
+    "runtime_concepts": ["packages/foo/src/model/", "packages/foo/src/event/"],
+    "config_formats": ["packages/foo/data/schemas/thing.schema.json"]
+  }
+}
+```
+
+Each key is an OKF concept folder; each value is the list of source path prefixes
+that folder is derived from. With no config present, `map`/`folders` are empty and
+`stale` is a no-op; `check` still works, since it lints the bundle's markdown
+alone. This is the only project-specific part — both the skill and the nudge read
+it from here.
+
+## Layout
+
+```
+.claude/skills/okf/
+├── SKILL.md                instructions Claude loads
+└── README.md               this file
+
+src/                        the okforge CLI (mechanics)
+├── cli.ts                  Commander entry; wires the subcommands below
+├── misc/
+│   └── okf_store.ts        mapping load, stale detection, conformance lint
+└── commands/
+    ├── map_command.ts      print the folder-to-source mapping
+    ├── folders_command.ts  list the concept folders
+    ├── sources_command.ts  print a folder's source paths
+    ├── stale_command.ts    folders whose source changed since HEAD
+    ├── check_command.ts    conformance + dead-link lint
+    └── nudge_command.ts    the Stop-hook nudge
+```
+
+## Conventions
+
+- File and folder names are snake_case. No kebab-case, no spaces.
+- Every non-index `.md` is a concept document: YAML frontmatter with a non-empty
+  `type`, then structural markdown (headings, lists, tables, code) using the
+  conventional `# Schema` / `# Examples` / `# Citations` sections where they
+  apply.
+- `index.md` is reserved and carries no frontmatter — except the root
+  `okf/index.md`, which declares `okf_version: "0.1"` and `type: Bundle Index`.
+- Cross-link concepts with bundle-relative absolute paths
+  (`/runtime_concepts/job_store.md`); cite real source files with repo-relative
+  paths (`../../packages/...`).
+- Ground every claim in real source. Do not invent fields, routes, flags, or
+  states; if uncertain, omit.
+
+## Reusing this in another project
+
+The skill is self-contained. Copy `.claude/skills/okf/`, register `npx okforge
+nudge` as a `Stop` hook in `.claude/settings.json`, and write an
+`.okforge.config.json` describing the target project's folder-to-source mapping.
+The mapping is the only project-specific part — both the skill and the nudge read
+it from there.

package/.claude/skills/okf/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: okf
+description: >-
+  Maintain the Open Knowledge Format (OKF) knowledge bundle under okf/. Use
+  whenever the user wants to update, refresh, or regenerate OKF docs, set up an
+  OKF bundle, check OKF conformance, or when source code that the bundle
+  documents (config schemas, web API routes, CLI commands, runtime subsystems,
+  example crews, ADRs) has changed and the docs need to catch up. Three modes:
+  scaffold (create the bundle), refresh (regenerate a folder's docs from current
+  source), and check (conformance and dead-link lint). Prefer this skill over
+  hand-editing okf/ so the format, the folder<->source mapping, and link
+  integrity stay consistent.
+---
+
+# Open Knowledge Format (OKF) maintenance
+
+OKF is an open, human- and agent-friendly format for knowledge — the metadata
+and curated insight that surrounds a system. This repo's bundle lives at `okf/`.
+Spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+
+The bundle is **derived** from source. Each folder is generated from specific
+files; when those files change, the folder's docs drift. This skill keeps three
+things consistent so you can focus on accurate prose: the OKF format, the
+folder<->source mapping, and link integrity.
+
+A bundled CLI owns the mechanics; you own the prose. Run it with `npx` from the
+project root (Node >= 20.12):
+
+```bash
+npx okforge <command>          # map | folders | sources <folder> | stale | check | nudge
+```
+
+## Pick the mode from what the user asked
+
+- **"refresh okf", "update the OKF docs for X", "the API changed, update okf"**
+  → Refresh mode (the common case).
+- **"set up okf", "create an OKF bundle", bundle missing** → Scaffold mode.
+- **"check okf", "is the bundle conformant", "any dead links"** → Check mode.
+
+## The folder <-> source mapping
+
+The mapping is **per-repository data**, declared in `.okforge.config.json` at the
+project root. okforge ships with none of it. The file shape is:
+
+```json
+{
+  "folders": {
+    "runtime_concepts": ["packages/foo/src/model/", "packages/foo/src/event/"],
+    "config_formats": ["packages/foo/data/schemas/thing.schema.json"]
+  }
+}
+```
+
+Each key is an OKF concept folder; each value is the list of source path prefixes
+that folder is derived from. `npx okforge map` prints the resolved mapping;
+`npx okforge sources <folder>` prints one folder's source paths;
+`npx okforge folders` lists the declared folders. Never hardcode the mapping in
+docs — read it from the config so there is one source of truth (the hook reads it
+too). When the codebase moves, edit `.okforge.config.json`.
+
+## Refresh mode
+
+1. Determine which folder(s) to refresh. If the user named one, use it. If they
+   said "whatever changed", run `npx okforge stale` — it lists folders whose
+   source changed since HEAD without the folder being edited.
+2. For each folder, run `npx okforge sources <folder>` and **READ those real
+   files**.
+3. Regenerate the affected concept docs from what you read, following the OKF
+   authoring rules below. Only rewrite docs whose underlying source actually
+   changed; leave correct docs untouched. Preserve existing filenames unless the
+   source they document was renamed or removed.
+4. If a concept's source was deleted, delete its doc and remove it from the
+   folder `index.md`. If a new source appeared, add a new concept doc and link
+   it from `index.md`.
+5. Update the folder `index.md`, and if folders were added/removed update the
+   root `okf/index.md`, the `.okforge.config.json` mapping, and prepend a dated
+   entry to `okf/log.md`.
+6. Run `npx okforge check` and resolve every problem it reports before finishing.
+
+## Scaffold mode
+
+Create `.okforge.config.json` at the project root with the folder<->source
+mapping for this repository (ask the user or infer it from the layout). Then
+create `okf/index.md` (the only file with frontmatter: `okf_version: "0.1"` and
+`type: Bundle Index`) and `okf/log.md`. Create the folders from the mapping and
+refresh each. Finish with `npx okforge check`.
+
+## Check mode
+
+Run `npx okforge check`. It verifies snake_case names, that every non-index `.md`
+has a non-empty frontmatter `type`, that sub-folder `index.md` files carry no
+frontmatter, and that bundle-relative `.md` links resolve. Report results; fix
+problems if the user asked you to.
+
+## OKF authoring rules (follow exactly when writing docs)
+
+- **File names**: snake_case only. No kebab-case, no spaces.
+- **Concept docs**: every non-index `.md` starts with a YAML frontmatter block
+  delimited by `---` lines. Required: `type` (non-empty, e.g. `Config Format`,
+  `Concept`, `Data Model`, `API Endpoint`, `CLI Command`, `Crew`, `Package`).
+  Recommended: `title`, `description` (one sentence), `resource` (path/URI of
+  the real underlying asset), `tags`, `timestamp` (ISO 8601 — set to today's
+  date on refresh).
+- **Body**: favor structural markdown — headings, lists, tables, fenced code —
+  over prose. Use conventional sections where they apply: `# Schema` (field/
+  shape), `# Examples` (code), `# Citations` (sources).
+- **Index files** (reserved): `index.md` has NO frontmatter (except the root
+  bundle index). It lists the folder's concepts as bulleted markdown links with
+  one-line descriptions, optionally grouped under `#` headings.
+- **Links**: cross-link concepts with bundle-relative absolute paths, e.g.
+  `[job store](/runtime_concepts/job_store.md)`. Link to real repo source files
+  (in `# Citations`) with repo-relative paths from the doc, e.g.
+  `../../packages/foo/src/model/job_store.ts`.
+- **Grounding (critical)**: every claim must come from the real source you read.
+  Do not invent field names, routes, flags, states, or behavior. If uncertain,
+  omit. Quote real schema fields and real route paths.
+- **Style**: plain English, no slang, no abbreviations.
+
+## Companion hook
+
+A `Stop` hook (`npx okforge nudge`, registered in `.claude/settings.json`) nudges
+at session end when mapped source changed but `okf/` was not updated. It reads the
+same `.okforge.config.json` mapping via `npx okforge stale`, so editing the
+mapping updates both the skill and the nudge.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerome Etienne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this 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.

package/README.md

@@ -0,0 +1,72 @@
+# okforge
+
+Deterministic mechanics and a Stop-hook nudge for the **okf** Claude Code skill,
+which maintains an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+(OKF) knowledge bundle under `okf/` in any repository.
+
+The skill prose lives in [`.claude/skills/okf/`](.claude/skills/okf); its
+deterministic mechanics live in [`src/`](src) as a small TypeScript CLI. The model
+writes the prose; the CLI answers "what is each folder derived from?" and "is the
+bundle still well-formed?".
+
+## Usable in any repository
+
+okforge ships with **no** repository-specific paths. Each repo declares its own
+folder-to-source mapping in `.okforge.config.json` at the project root:
+
+```json
+{
+  "folders": {
+    "runtime_concepts": ["packages/foo/src/model/", "packages/foo/src/event/"],
+    "config_formats": ["packages/foo/data/schemas/thing.schema.json"]
+  }
+}
+```
+
+With no config present, `map`/`folders` are empty and `stale` is a no-op; `check`
+still works, since it lints the bundle's markdown alone.
+
+## The `okforge` CLI
+
+Run with `npx` (Node >= 20.12). `<dir>` defaults to the current directory.
+
+| Command | Purpose |
+|---|---|
+| `okforge map [<dir>]` | Print the full folder-to-source mapping. |
+| `okforge folders [<dir>]` | List the OKF concept folders. |
+| `okforge sources <folder> [<dir>]` | Print the source paths a folder is derived from. |
+| `okforge stale [<dir>]` | List folders whose source changed since HEAD while the folder was not edited. |
+| `okforge check [<dir>]` | Conformance + dead-link lint; exits non-zero on problems. |
+| `okforge nudge` | Stop-hook entry: read the hook payload on stdin and maybe remind. |
+
+## Development
+
+```bash
+npm install
+npm run okforge -- <command>   # run the CLI from source via tsx
+npm run typecheck              # tsc --noEmit
+npm run build                  # compile to dist/
+```
+
+## Layout
+
+```
+src/
+├── cli.ts                  Commander entry; wires the subcommands below
+├── misc/
+│   └── okf_store.ts        mapping load, stale detection, conformance lint
+└── commands/
+    ├── map_command.ts      print the folder-to-source mapping
+    ├── folders_command.ts  list the concept folders
+    ├── sources_command.ts  print a folder's source paths
+    ├── stale_command.ts    folders whose source changed since HEAD
+    ├── check_command.ts    conformance + dead-link lint
+    └── nudge_command.ts    the Stop-hook nudge
+.claude/skills/okf/
+├── SKILL.md                instructions Claude loads
+└── README.md               human-facing skill overview
+```
+
+## License
+
+MIT © Jerome Etienne

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import Fs from 'node:fs';
+import Path from 'node:path';
+import { Command } from 'commander';
+import Chalk from 'chalk';
+import { MapCommand } from './commands/map_command.js';
+import { FoldersCommand } from './commands/folders_command.js';
+import { SourcesCommand } from './commands/sources_command.js';
+import { StaleCommand } from './commands/stale_command.js';
+import { CheckCommand } from './commands/check_command.js';
+import { NudgeCommand } from './commands/nudge_command.js';
+import { InstallCommand } from './commands/install_command.js';
+/** Wire up the subcommands and run them. */
+async function main() {
+    const packageJsonPath = Path.join(import.meta.dirname, '..', 'package.json');
+    const { version } = JSON.parse(Fs.readFileSync(packageJsonPath, 'utf8'));
+    const program = new Command();
+    program
+        .name('okforge')
+        .description('Deterministic mechanics and Stop-hook nudge for the okf (Open Knowledge Format) skill')
+        .version(version, '-V, --version', 'output the version number');
+    program
+        .command('folders')
+        .description('List the OKF concept folders declared in .okforge.config.json')
+        .argument('[dir]', 'Repository root', '.')
+        .action((dir) => {
+        for (const folder of FoldersCommand.folders(Path.resolve(dir))) {
+            console.log(folder);
+        }
+    });
+    program
+        .command('map')
+        .description('Print the full folder -> sources mapping')
+        .argument('[dir]', 'Repository root', '.')
+        .action((dir) => {
+        for (const line of MapCommand.map(Path.resolve(dir))) {
+            console.log(line);
+        }
+    });
+    program
+        .command('sources')
+        .description('Print the source paths a folder is derived from')
+        .argument('<folder>', 'OKF concept folder')
+        .argument('[dir]', 'Repository root', '.')
+        .action((folder, dir) => {
+        for (const source of SourcesCommand.sources(Path.resolve(dir), folder)) {
+            console.log(source);
+        }
+    });
+    program
+        .command('stale')
+        .description('List folders whose source changed since HEAD while the folder was not edited')
+        .argument('[dir]', 'Repository root', '.')
+        .action((dir) => {
+        for (const line of StaleCommand.stale(Path.resolve(dir))) {
+            console.log(line);
+        }
+    });
+    program
+        .command('check')
+        .description('Conformance + dead-link lint; exits non-zero on problems')
+        .argument('[dir]', 'Repository root', '.')
+        .action((dir) => {
+        const cwd = Path.resolve(dir);
+        let result;
+        try {
+            result = CheckCommand.check(cwd);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(message);
+            process.exit(2);
+        }
+        for (const problem of result.problems) {
+            console.log(problem);
+        }
+        if (result.problems.length === 0) {
+            console.log(result.summary);
+            return;
+        }
+        console.error(result.summary);
+        process.exit(1);
+    });
+    program
+        .command('nudge')
+        .description('Stop-hook companion: read the hook payload on stdin and maybe remind')
+        .action(async () => {
+        await NudgeCommand.nudge();
+    });
+    program
+        .command('install')
+        .description('Copy the bundled okf skill into an AI agent folder (e.g. .claude)')
+        .argument('[agent_folder]', 'Destination agent folder', '.')
+        .action((agentFolder) => {
+        const result = InstallCommand.install(agentFolder);
+        for (const file of result.files) {
+            console.log(`${Chalk.green(file.action)} ${file.destination}`);
+        }
+        console.log(Chalk.bold(`\n${result.files.length} file(s) → ${result.destinationDir}`));
+        console.log('Next: register `npx okforge nudge` as a Stop hook in .claude/settings.json.');
+    });
+    await program.parseAsync(process.argv);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(Chalk.red(`error: ${message}`));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/check_command.d.ts

@@ -0,0 +1,15 @@
+/** Outcome of a conformance run: the problems found and a summary line. */
+export type CheckResult = {
+    problems: string[];
+    summary: string;
+};
+/** `check` — conformance + dead-link lint of the `okf/` bundle. */
+export declare class CheckCommand {
+    /**
+     * Lint the bundle under `cwd`. Returns the problems and a summary line:
+     * `OK: N concept docs conformant` when clean, `FAILED: N problem(s)` otherwise.
+     * Throws when there is no `okf/` bundle.
+     */
+    static check(cwd: string): CheckResult;
+}
+//# sourceMappingURL=check_command.d.ts.map

package/dist/commands/check_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check_command.d.ts","sourceRoot":"","sources":["../../src/commands/check_command.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,mEAAmE;AACnE,qBAAa,YAAY;IACxB;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;CAOtC"}

package/dist/commands/check_command.js

@@ -0,0 +1,17 @@
+import { OkfStore } from '../misc/okf_store.js';
+/** `check` — conformance + dead-link lint of the `okf/` bundle. */
+export class CheckCommand {
+    /**
+     * Lint the bundle under `cwd`. Returns the problems and a summary line:
+     * `OK: N concept docs conformant` when clean, `FAILED: N problem(s)` otherwise.
+     * Throws when there is no `okf/` bundle.
+     */
+    static check(cwd) {
+        const problems = OkfStore.check(cwd);
+        if (problems.length === 0) {
+            return { problems, summary: `OK: ${OkfStore.conceptCount(cwd)} concept docs conformant` };
+        }
+        return { problems, summary: `FAILED: ${problems.length} problem(s)` };
+    }
+}
+//# sourceMappingURL=check_command.js.map

package/dist/commands/check_command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check_command.js","sourceRoot":"","sources":["../../src/commands/check_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAQhD,mEAAmE;AACnE,MAAM,OAAO,YAAY;IACxB;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,GAAW;QACvB,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,0BAA0B,EAAE,CAAC;QAC3F,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,QAAQ,CAAC,MAAM,aAAa,EAAE,CAAC;IACvE,CAAC;CACD"}

package/dist/commands/folders_command.d.ts

@@ -0,0 +1,6 @@
+/** `folders` — list the OKF concept folders, one per line. */
+export declare class FoldersCommand {
+    /** The OKF concept folder names declared in `cwd`'s config, in declared order. */
+    static folders(cwd: string): string[];
+}
+//# sourceMappingURL=folders_command.d.ts.map

package/dist/commands/folders_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folders_command.d.ts","sourceRoot":"","sources":["../../src/commands/folders_command.ts"],"names":[],"mappings":"AAEA,8DAA8D;AAC9D,qBAAa,cAAc;IAC1B,kFAAkF;IAClF,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;CAGrC"}

package/dist/commands/folders_command.js

@@ -0,0 +1,9 @@
+import { OkfStore } from '../misc/okf_store.js';
+/** `folders` — list the OKF concept folders, one per line. */
+export class FoldersCommand {
+    /** The OKF concept folder names declared in `cwd`'s config, in declared order. */
+    static folders(cwd) {
+        return OkfStore.folders(cwd);
+    }
+}
+//# sourceMappingURL=folders_command.js.map

package/dist/commands/folders_command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folders_command.js","sourceRoot":"","sources":["../../src/commands/folders_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,8DAA8D;AAC9D,MAAM,OAAO,cAAc;IAC1B,kFAAkF;IAClF,MAAM,CAAC,OAAO,CAAC,GAAW;QACzB,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;CACD"}

package/dist/commands/install_command.d.ts

@@ -0,0 +1,25 @@
+/** Outcome of copying a single skill file into the destination folder. */
+export type InstalledFile = {
+    name: string;
+    action: 'created' | 'updated';
+    destination: string;
+};
+/** Summary returned by {@link InstallCommand.install}. */
+export type InstallResult = {
+    destinationDir: string;
+    files: InstalledFile[];
+};
+/** `install` — copy the bundled okf skill into an AI agent folder (e.g. `.claude`). */
+export declare class InstallCommand {
+    /**
+     * Copy the bundled `skills/okf/` tree into `agentFolder` (the agent directory,
+     * e.g. `.claude`), preserving the `skills/okf/...` layout, to set the skill up
+     * in a target project. Machine-local settings are never copied.
+     * @param agentFolder Destination agent folder; the caller defaults it to `.`.
+     * @returns The destination directory and the per-file outcome.
+     */
+    static install(agentFolder: string): InstallResult;
+    /** Paths of every file under `dir`, relative to `dir`, recursively. */
+    static listFiles(dir: string): string[];
+}
+//# sourceMappingURL=install_command.d.ts.map

package/dist/commands/install_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install_command.d.ts","sourceRoot":"","sources":["../../src/commands/install_command.ts"],"names":[],"mappings":"AAGA,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;CACvB,CAAC;AAEF,uFAAuF;AACvF,qBAAa,cAAc;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa;IAkBlD,uEAAuE;IACvE,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;CAavC"}

package/dist/commands/install_command.js

@@ -0,0 +1,45 @@
+import Fs from 'node:fs';
+import Path from 'node:path';
+/** `install` — copy the bundled okf skill into an AI agent folder (e.g. `.claude`). */
+export class InstallCommand {
+    /**
+     * Copy the bundled `skills/okf/` tree into `agentFolder` (the agent directory,
+     * e.g. `.claude`), preserving the `skills/okf/...` layout, to set the skill up
+     * in a target project. Machine-local settings are never copied.
+     * @param agentFolder Destination agent folder; the caller defaults it to `.`.
+     * @returns The destination directory and the per-file outcome.
+     */
+    static install(agentFolder) {
+        const skillsDir = Path.join(import.meta.dirname, '..', '..', '.claude', 'skills');
+        if (Fs.existsSync(skillsDir) === false) {
+            throw new Error(`bundled skill files not found at ${skillsDir}`);
+        }
+        const destinationDir = Path.resolve(agentFolder);
+        const files = [];
+        for (const relative of InstallCommand.listFiles(skillsDir)) {
+            const name = Path.join('skills', relative);
+            const destination = Path.join(destinationDir, name);
+            const exists = Fs.existsSync(destination);
+            Fs.mkdirSync(Path.dirname(destination), { recursive: true });
+            Fs.copyFileSync(Path.join(skillsDir, relative), destination);
+            files.push({ name, action: exists === true ? 'updated' : 'created', destination });
+        }
+        return { destinationDir, files };
+    }
+    /** Paths of every file under `dir`, relative to `dir`, recursively. */
+    static listFiles(dir) {
+        const result = [];
+        for (const entry of Fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory() === true) {
+                for (const nested of InstallCommand.listFiles(Path.join(dir, entry.name))) {
+                    result.push(Path.join(entry.name, nested));
+                }
+            }
+            else {
+                result.push(entry.name);
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=install_command.js.map

package/dist/commands/install_command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install_command.js","sourceRoot":"","sources":["../../src/commands/install_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAe7B,uFAAuF;AACvF,MAAM,OAAO,cAAc;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,WAAmB;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAClF,IAAI,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,KAAK,KAAK,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,oCAAoC,SAAS,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACjD,MAAM,KAAK,GAAoB,EAAE,CAAC;QAClC,KAAK,MAAM,QAAQ,IAAI,cAAc,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC3C,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;YACpD,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;YAC1C,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,WAAW,CAAC,CAAC;YAC7D,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,SAAS,CAAC,GAAW;QAC3B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YAClE,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC;gBAClC,KAAK,MAAM,MAAM,IAAI,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;oBAC3E,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;gBAC5C,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;QACF,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;CACD"}

package/dist/commands/map_command.d.ts

@@ -0,0 +1,6 @@
+/** `map` — print the full folder -> sources mapping. */
+export declare class MapCommand {
+    /** The mapping as printable lines: `## <folder>` headers with `  - <source>` rows. */
+    static map(cwd: string): string[];
+}
+//# sourceMappingURL=map_command.d.ts.map

package/dist/commands/map_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map_command.d.ts","sourceRoot":"","sources":["../../src/commands/map_command.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,qBAAa,UAAU;IACtB,sFAAsF;IACtF,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;CAUjC"}