okfcli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Deprit
+
+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

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# okfcli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/okfcli)](https://www.npmjs.com/package/okfcli)
+[![CI](https://github.com/lucasdeprit/okfcli/actions/workflows/ci.yml/badge.svg)](https://github.com/lucasdeprit/okfcli/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/okfcli)](LICENSE)
+
+Create and maintain project wikis in [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/open-knowledge-format), with the same structure in every project.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `okfcli init [folder]` | Create the wiki (default `./wiki`) and connect it to your coding agents (Copilot by default; `--claude`, `--codex`, `--opencode`, `--cursor`) |
+| `okfcli new <type> <name> --description "..."` | Create a page from its template and add it to the index |
+| `okfcli validate [--fix]` | Check the wiki and list what nobody has reviewed. `--fix` repairs the mechanical issues |
+| `okfcli verify <path> --by human:<id>` | Mark a page as reviewed |
+
+```bash
+okfcli init docs/wiki
+okfcli new pattern state-management --description "How screen state is structured."
+okfcli validate --fix
+okfcli verify patterns/state-management --by human:ana
+```
+
+- **Types for `new`:** `overview` `architecture` `pattern` `convention` `workflow` `testing` `feature` `module` `interface` `operation` `troubleshooting`
+- **Every command:** `--json` for machine-readable output, `--wiki <folder>` to pick a wiki (otherwise it is found from the current directory)
+- **Help:** `okfcli --help`, `okfcli <command> --help`
+
+## Install
+
+Needs Node 22 or later.
+
+```bash
+npm install -g okfcli          # gives you the `okfcli` command
+npx okfcli init docs/wiki      # or run it without installing
+```
+
+Pin a version with `npm install -g okfcli@0.1.0`. To upgrade, install again, then run `okfcli init` in each project to refresh the generated agent files.
+
+## What you get
+
+```
+docs/wiki/
+├── index.md
+├── .okf-profile.yaml     settings: extra folders, rule severities
+├── overview/             what the project is
+├── architecture/         structure and rules
+├── patterns/             how we implement things
+├── conventions/          style and naming
+├── workflows/            how we work
+├── testing/              how we test
+└── (features/ modules/ interfaces/ operations/ troubleshooting/)  optional, created by `okfcli new`
+```
+
+Every folder has an `index.md`, generated for you. Every page has `type`, `title` and `description`, plus the sections its type requires.
+
+## How it works
+
+- **The CLI does the mechanical work:** folders, indexes, page skeletons, structure checks. Nobody edits `index.md` by hand.
+- **Agents write the content:** they fill in the sections of the pages `okfcli new` creates.
+- **People review:** a page is unreviewed until someone runs `okfcli verify` (or writes the `verified` entry by hand). If a verified page changes afterwards, `validate` reports it as outdated.
+- **No history files:** the history of the wiki is left to git.
+
+## Agents
+
+`okfcli init` also writes, relative to the directory where you run it, the files that connect the wiki to your coding agents. Pass one flag per tool you use; without any flag it connects GitHub Copilot:
+
+```bash
+okfcli init                      # Copilot
+okfcli init --claude             # Claude Code
+okfcli init --claude --codex     # several at once
+```
+
+| Flag | Pointer block in | Skills in |
+|---|---|---|
+| `--copilot` (default) | `AGENTS.md` (or `.github/copilot-instructions.md` if that is what the project uses) | `.github/skills/` |
+| `--claude` | `CLAUDE.md` | `.claude/skills/` |
+| `--codex`, `--opencode`, `--cursor` | `AGENTS.md` | `.agents/skills/` |
+
+The pointer block makes the agent always know the wiki exists. The three skills are `okf-consult-wiki`, `okf-update-wiki` and `okf-review-wiki`. `okfcli` never deletes files, so files of an agent you stop passing stay where they are.
+
+The skills call `okfcli`, so install it globally on the machines where agents run. Run `okfcli init` again to refresh these files; it never touches the wiki pages. `--no-agents` skips them.
+
+## Contract
+
+The rules a wiki must follow (folders, page types, required sections, review, checks) are in [SPEC.md](https://github.com/lucasdeprit/okfcli/blob/main/SPEC.md).
+
+## Development
+
+```bash
+npm install
+npm test                          # builds to dist/ and runs the tests
+node dist/bin/okfcli.js --help    # run from a clone
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/SPEC.md

@@ -0,0 +1,243 @@
+# Project wiki contract on top of OKF (draft 0.1)
+
+Status: **draft under review**. This defines what a wiki must satisfy; the `okfcli` CLI implements and enforces it.
+
+## 1. Goal
+
+Every project wiki must have the same shape, so that:
+
+- an agent (or a person) knows where to look in any project without knowing it beforehand;
+- agents can maintain the wiki by following fixed rules;
+- the structure lasts over time without growing in a disorderly way.
+
+### Principle: the CLI does the mechanical work, the agent only writes content
+
+Anything that can be decided with rules is done by the CLI, deterministically and without spending tokens. The agent is limited to what requires judgement: writing the content of the pages.
+
+| The CLI does | The agent does |
+|---|---|
+| Create folders and `index.md` | Decide what deserves a page |
+| Create a page with frontmatter and a section skeleton | Fill in the sections |
+| Register the page in the `index.md` of its folder | Write the `# Why` and the examples |
+| Stamp `verified` with actor, date and content hash | Decide whether something should be marked `deprecated` |
+| Validate structure, sections, links and indexes | Review content against the code |
+| Fix only the mechanical issues (`validate --fix`) | Fix the content problems that `validate` reports |
+| Fix only the mechanical issues (`validate --fix`) | |
+
+Design consequences:
+
+- One command per operation. `new` creates the page and registers it in the index, so the agent does not have to edit two files.
+- The skills generated for agents tell them to **use the CLI** and not to create or hand-edit `index.md` or the `verified` entries.
+- `validate` messages say which file, which rule and how to fix it, so the agent reads only what it needs.
+- `validate` and `index` can run in CI or in a hook without any agent.
+
+## 2. Layers
+
+1. **OKF v0.2** (Google, [open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format)): the base format. A wiki is a *bundle*: a tree of `.md` files with YAML frontmatter and reserved `index.md` (and, optionally, `log.md`).
+2. **Base profile** (this document): additional rules, stricter than OKF.
+3. **Project extension**: folders and rules specific to a project, without removing those of the base profile.
+
+A wiki that breaks the profile but satisfies OKF is still valid OKF.
+
+## 3. Structure
+
+```
+wiki/
+├── index.md
+├── .okf-profile.yaml
+├── overview/          # core
+├── architecture/      # core
+├── patterns/          # core
+├── conventions/       # core
+├── workflows/         # core
+├── testing/           # core
+├── features/          # optional
+├── modules/           # optional
+├── interfaces/        # optional
+├── operations/        # optional
+└── troubleshooting/   # optional
+```
+
+Folder names are fixed and do not depend on any technology. Whatever is specific to a project (a framework, an internal package) goes in pages, not in folders of the standard.
+
+### General rules
+
+- Every folder has an `index.md`.
+- File and folder names in `kebab-case`, without repeating the folder name (`modules/auth/core.md`, not `modules/auth/auth-core.md`).
+- Own folders can be added (declared in `extra_folders`); core folders cannot be removed or renamed.
+- There is no decisions folder. The reason for a rule lives in the `# Why` section of its page. What changes is edited in the page; the history is left to git. What stops applying is marked `status: deprecated`.
+- Page content can be in any language. The `type` names, frontmatter fields and required section names are in English.
+
+### Folder, `type` and minimum sections
+
+| Folder | `type` | Sections required in every page |
+|---|---|---|
+| `overview/` | `Overview` | `# Purpose`, `# Scope` |
+| `architecture/` | `Architecture` | `# Overview`, `# Rules`, `# Why` |
+| `patterns/` | `Pattern` | `# When to use`, `# How`, `# Example`, `# Why` |
+| `conventions/` | `Convention` | `# Rule`, `# Examples` |
+| `workflows/` | `Workflow` | `# Goal`, `# Steps` |
+| `testing/` | `Testing` | `# Scope`, `# How to run`, `# Rules` |
+| `features/` | `Feature` | `# Summary`, `# Behavior` |
+| `modules/` | `Module` | `# Responsibility`, `# Public API` |
+| `interfaces/` | `Interface` | `# Contract`, `# Consumers` |
+| `operations/` | `Operation` | `# When`, `# Steps` |
+| `troubleshooting/` | `Troubleshooting` | `# Symptom`, `# Cause`, `# Fix` |
+
+A page may have more sections. Only these are required.
+
+### Required pages
+
+- `overview/project.md`: what the project is.
+- `workflows/update-wiki.md`: when and how the wiki is updated (see section 6).
+- `testing/` must contain at least one testing strategy page (so `testing/index.md` links to it). `okfcli init` scaffolds `testing/strategy.md` (title, frontmatter and the required sections, unfilled); any page in `testing/` satisfies the rule, so a project may rename or replace it.
+
+## 4. Frontmatter
+
+Every concept page (not `index.md`) carries:
+
+| Field | Requirement | Notes |
+|---|---|---|
+| `type` | error if missing | Must match the type of its folder |
+| `title` | error if missing | |
+| `description` | error if missing | One sentence |
+| `tags` | optional | List of strings |
+| `verified` | see below | List of `{ by, at, hash }`: who reviewed the page, when, and a fingerprint of the content they read |
+| `status` | optional | Only `deprecated` is acted upon; `draft` and `stable` are accepted (absent = `stable`) |
+
+There are no `generated` or `stale_after` fields: nothing expires by date, and who created or changed a page is left to git.
+
+### Review: `verified`
+
+Every page is born **unreviewed**. A page counts as reviewed when it has a valid `verified` entry:
+
+- **Who decides.** A person, not the tool. A person verifies either by running `okfcli verify <path> --by human:<id>` or by writing the entry by hand in the page frontmatter. Agents may help (the review skill walks the person through the unreviewed pages), but they only run `okfcli verify --by human:<id>` after the person has confirmed.
+- **Tiers** (from OKF): no entry = *unverified*; only machine actors = *machine-confirmed*; any `human:<id>` = *human-reviewed*.
+- **Outdated.** `okfcli verify` stores a `hash` of the content that was read (frontmatter except `verified` and `status`, plus body). If the page is edited afterwards the hash no longer matches and the verification is reported as *outdated* until it is verified again. Entries without a hash (written by hand) are always accepted and never go outdated.
+- **Nagging.** `validate` warns about unreviewed and outdated pages, so a team can see what nobody has read yet. Projects that want to enforce review can raise `frontmatter.verified` and `frontmatter.verified-outdated` to `error` in their profile. Deprecated pages are not asked to be reviewed.
+- **Deprecating.** `status: deprecated` is only ever set by a person or an agent editing the page; the tool never deprecates anything by itself.
+
+Actor convention (OKF): `human:<id>`, `process:<id>` or `<tool>/<version>`.
+
+## 5. `index.md`
+
+**`index.md`** (every folder). No frontmatter, except the root one, which carries `okf_version: "0.2"`. One line per page, as OKF asks:
+
+```markdown
+# Patterns
+
+* [State management](/patterns/state-management.md) - How the state of a screen is structured.
+```
+
+Indexes are generated by `okfcli index` and are never edited by hand. Every page of the folder must appear in its `index.md`, and every entry must point to a page that exists.
+
+**`log.md`.** OKF reserves this name for an update history, but `okfcli` does not create or manage it: the history of a wiki is left to git. If a project keeps its own `log.md`, it is never treated as a concept page.
+
+## 6. Maintenance by agents
+
+Agents update the wiki. `workflows/update-wiki.md` defines the standard procedure:
+
+1. If a change affects a rule, a pattern or a convention, the affected page is edited; a new one is not added.
+2. The `index.md` of the folder is updated (by `okfcli`, never by hand).
+3. The page stays unreviewed until a person verifies it; the agent does not verify its own work as a person.
+4. If a page stops applying, it is marked `status: deprecated`.
+
+`workflows/` links to `patterns/`: every workflow step that depends on a way of implementing something links to its pattern.
+
+## 7. Configuration: `.okf-profile.yaml`
+
+```yaml
+profile: base@0.1          # base profile and version
+language: en               # language of the content (informational)
+severity:                  # overrides the severity of a rule: error | warning | off
+  frontmatter.verified: error
+  frontmatter.verified-outdated: error
+extra_folders:             # project-specific folders
+  - name: mobile
+    type: Mobile
+    sections: ["# Summary"]
+```
+
+## 8. Checks (`validate`)
+
+Every rule has a stable id that can be used in `severity`.
+
+| Rule id | Check | Default severity | Fixed by `--fix` |
+|---|---|---|---|
+| `okf.frontmatter` | Concept pages have parseable YAML frontmatter | error | |
+| `okf.type` | `type` is present and non-empty | error | |
+| `okf.index` | `index.md` has no frontmatter (the root one only `okf_version`) | error | |
+| `structure.core-folder` | Every core folder exists | error | yes |
+| `structure.required-page` | Required pages exist | error | yes |
+| `structure.testing-page` | `testing/` has at least one strategy page | error | yes (scaffolds `testing/strategy.md`) |
+| `structure.unknown-folder` | Pages live in a core, optional or declared folder | warning | |
+| `page.type` | `type` matches the type of the folder | error | |
+| `page.sections` | Required sections are present | error | yes |
+| `page.todo` | No unfilled `<!-- TODO -->` placeholders | warning | |
+| `frontmatter.title` | `title` present | error | |
+| `frontmatter.description` | `description` present | error | |
+| `frontmatter.status` | `status`, if present, is `draft`, `stable` or `deprecated` | error | |
+| `frontmatter.verified` | Page has been reviewed (has a `verified` entry) | warning | |
+| `frontmatter.verified-outdated` | The page has not changed since it was verified | warning | |
+| `name.kebab-case` | File and folder names are `kebab-case` | error | |
+| `index.out-of-date` | Every `index.md` matches the pages in its folder: no page missing from it, no entry pointing to a page that no longer exists, no folder without an `index.md` | error | yes |
+| `link.broken` | Internal links point to existing pages | warning | |
+| `page.orphan` | Some other concept page links to it | warning | |
+
+`validate` exits with code 1 if there is any error (`--strict`: any warning too). `--json` prints every issue with `rule`, `severity`, `file`, `message` and `fix`.
+
+## 9. CLI (Node, `npx`)
+
+| Command | What it does |
+|---|---|
+| `init` | Creates the wiki with the core, the indexes and `.okf-profile.yaml` |
+| `new <type> <name>` | Creates a page with its template and frontmatter and registers it in the index |
+| `validate` | Runs the checks of section 8, including which pages nobody has reviewed or that changed after being verified, with a review summary; `--fix` repairs the mechanical issues (folders, required pages, section skeletons, indexes) |
+| `verify <path>` | Records a review in `verified` (`--by <actor>`, one entry per actor) with a hash of the content. Refuses pages with unfilled TODOs unless `--force` |
+
+There are deliberately only four commands: people should not have to learn an ecosystem. Indexes are kept up to date by `new` and `validate --fix`, so there is no `index` command; the review state is part of `validate`, so there is no `status` command; the agent files are refreshed by running `init` again, so there is no `update` command.
+
+## 10. Agent integration
+
+As OpenSpec does, the connection with agents is made with **generated files** in the paths each tool reads, plus a CLI with `--json` output. There is no MCP server and no hooks in the first version.
+
+Supported agents, chosen with one flag each on `init` (`--copilot` is the default when none is given). Several can be combined; agents that share a destination write it once:
+
+| Flag | Instructions file (carries the pointer block) | Skills folder |
+|---|---|---|
+| `--copilot` | `AGENTS.md`, or `.github/copilot-instructions.md` if the project already uses it | `.github/skills/` |
+| `--claude` | `CLAUDE.md` (or `.claude/CLAUDE.md` if that is the one that exists) | `.claude/skills/` |
+| `--codex` | `AGENTS.md` | `.agents/skills/` |
+| `--opencode` | `AGENTS.md` | `.agents/skills/` |
+| `--cursor` | `AGENTS.md` | `.agents/skills/` |
+
+Notes on Claude Code: it reads `AGENTS.md` only when the project has no `CLAUDE.md` at all, so with `--claude` the block goes into `CLAUDE.md`. If `CLAUDE.md` does not exist yet and `AGENTS.md` does (or is written in the same run), the new `CLAUDE.md` starts with `@AGENTS.md`, so it never hides the project's own instructions. Combining `--copilot --claude` therefore shows the block in both files, which is harmless. `init` never deletes files: those of an agent you stop passing stay where they are. The Cursor skills path comes from third-party documentation and is the least verified.
+
+The rest of this section describes the files for GitHub Copilot in VS Code (paths verified in the VS Code documentation, vscode-docs, October 2026); the other agents get the same files at their own paths:
+
+| Piece | File generated by `init` (running it again refreshes them) | Purpose |
+|---|---|---|
+| Pointer to the wiki | Marked block inside `AGENTS.md` (or `.github/copilot-instructions.md` if the project already uses it) | So the agent always knows the wiki exists and consults it before touching code |
+| Consult skill | `.github/skills/okf-consult-wiki/SKILL.md` | Read `index.md` and drill into the relevant pages |
+| Update skill | `.github/skills/okf-update-wiki/SKILL.md` | Edit pages in place, create new ones with `okfcli new`, then `okfcli validate --fix` and fix what it reports (so there is no separate validation skill) |
+| Review skill | `.github/skills/okf-review-wiki/SKILL.md` | List unreviewed pages with `validate --json`, walk the person through them one by one, and run `verify --by human:<id>` only after the person confirms |
+
+Notes on Copilot:
+
+- **Skills** (`SKILL.md` with required `name` and `description`, `name` equal to the folder name) follow the open standard agentskills.io. Copilot reads them in `.github/skills/`, `.claude/skills/` and `.agents/skills/`, and they show up as `/` commands in chat. They are used instead of *prompt files* (`.github/prompts/*.prompt.md`), which only work in the Local harness.
+- `AGENTS.md` is read by Copilot, and also by Codex and others. In the Local harness it depends on the `chat.useAgentsMdFile` setting.
+- `.github/copilot-instructions.md` is also read, with `github.copilot.chat.codeGeneration.useInstructionFiles`.
+- A skill is activated by its `description` and the agent decides whether to load it; that is why the pointer exists, since it is always loaded.
+- Generated files belong to the CLI: running `init` again regenerates them (and never touches the pages). Project content goes outside the markers. Each skill carries a header comment saying so.
+- Paths are relative to the directory where `init` runs (the project root). The pointer block goes in the file that already has it, else in `AGENTS.md` if it exists, else in `.github/copilot-instructions.md` if it exists, else a new `AGENTS.md`.
+- The wiki path is written into the generated files, and the update skill lists the types and sections of every folder of the profile, including `extra_folders`.
+- `--no-agents` skips all of this, whatever other agent flags are present.
+
+Output for agents: `--json` on every command. `new` already returns the sections to fill in, so no separate command is needed to get a page template.
+
+## 11. Open questions
+
+- Minimum sections per folder: are they the right ones or too rigid?
+- Is `# Why` required in `conventions/`? Currently not.
+- Is a folder needed for raw sources (original documents the wiki is derived from)?
+- Exact template of `workflows/update-wiki.md`.

package/dist/bin/okfcli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/okfcli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
+    console.error('This is a bug in okfcli; please report it with the command you ran.');
+    process.exitCode = 2;
+});

package/dist/src/cli.d.ts

@@ -0,0 +1,7 @@
+interface RunOptions {
+    cwd?: string;
+    out?: (text: string) => void;
+    err?: (text: string) => void;
+}
+export declare function run(argv: string[], { cwd, out, err }?: RunOptions): Promise<number>;
+export {};

package/dist/src/cli.js

@@ -0,0 +1,122 @@
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { UserError, errorCode } from './core/util.js';
+import { findWikiRoot } from './wiki/root.js';
+import { init, initHelp } from './commands/init.js';
+import { AGENT_NAMES, DEFAULT_AGENTS } from './generate/targets.js';
+import { newPage, newHelp } from './commands/new.js';
+import { validateCommand, validateHelp } from './commands/validate.js';
+import { verifyCommand, verifyHelp } from './commands/verify.js';
+// The compiled file lives in dist/src/, two levels below package.json.
+const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+const HELP = `okfcli ${version} - scaffolding and management of OKF wikis
+
+Commands:
+  init [folder]             Create a wiki and connect it to your agents (${AGENT_NAMES.map((n) => `--${n}`).join(' ')}; default: ${DEFAULT_AGENTS.join(', ')})
+  new <type> <name>         Create a page and register it in its index
+  validate [--fix]          Check the wiki (structure, indexes, review state); --fix repairs the mechanical issues
+  verify <path>             Record that a page has been reviewed
+
+Common options:
+  --wiki <folder>           Wiki to operate on (by default it is searched from the current directory)
+  --json                    JSON output, for agents and scripts
+  -h, --help                Help for a command
+  -v, --version
+
+Run "okfcli <command> --help" for details.`;
+const COMMON = {
+    wiki: { type: 'string' },
+    json: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+};
+const str = (v) => (typeof v === 'string' ? v : undefined);
+const flag = (v) => v === true;
+// The agents named by flags; undefined (not an empty list) means none was given, so init uses its default.
+const pickedAgents = (values) => {
+    const picked = AGENT_NAMES.filter((name) => flag(values[name]));
+    return picked.length ? picked : undefined;
+};
+const COMMANDS = {
+    init: {
+        help: initHelp,
+        options: {
+            with: { type: 'string' },
+            language: { type: 'string' },
+            'no-agents': { type: 'boolean' },
+            // One boolean flag per supported agent (--claude, --codex, ...).
+            ...Object.fromEntries(AGENT_NAMES.map((name) => [name, { type: 'boolean' }])),
+        },
+        run: ({ values, positionals, cwd }) => init({
+            cwd,
+            dir: positionals[0],
+            withFolders: str(values.with)?.split(',').map((s) => s.trim()).filter(Boolean) ?? [],
+            language: str(values.language),
+            agents: flag(values['no-agents']) ? [] : pickedAgents(values),
+            version,
+        }),
+    },
+    new: {
+        help: newHelp,
+        options: { title: { type: 'string' }, description: { type: 'string' } },
+        run: ({ values, positionals, root }) => {
+            const wiki = root();
+            const [type, name] = positionals;
+            if (!type || !name)
+                throw new UserError('Usage: okfcli new <type> <name> --description "..."');
+            return newPage({ root: wiki, type, name, title: str(values.title), description: str(values.description) });
+        },
+    },
+    verify: {
+        help: verifyHelp,
+        options: { by: { type: 'string' }, force: { type: 'boolean' } },
+        run: ({ values, positionals, root, cwd }) => verifyCommand({ root: root(), cwd, path: positionals[0], by: str(values.by), force: flag(values.force), version }),
+    },
+    validate: {
+        help: validateHelp,
+        options: { fix: { type: 'boolean' }, strict: { type: 'boolean' } },
+        run: ({ values, root }) => validateCommand({ root: root(), fix: flag(values.fix), strict: flag(values.strict) }),
+    },
+};
+export async function run(argv, { cwd = process.cwd(), out = console.log, err = console.error } = {}) {
+    const [name, ...rest] = argv;
+    if (name === undefined || name === '-h' || name === '--help' || name === 'help') {
+        out(HELP);
+        return 0;
+    }
+    if (name === '-v' || name === '--version') {
+        out(version);
+        return 0;
+    }
+    const command = Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : undefined;
+    if (!command) {
+        err(`Unknown command: ${name}\n\n${HELP}`);
+        return 1;
+    }
+    try {
+        const { values, positionals } = parseArgs({
+            args: rest,
+            options: { ...COMMON, ...command.options },
+            allowPositionals: true,
+        });
+        if (values.help) {
+            out(command.help);
+            return 0;
+        }
+        const result = await command.run({ values, positionals, cwd, root: () => findWikiRoot(cwd, str(values.wiki)) });
+        if (values.json) {
+            const { text: _text, ...data } = result;
+            out(JSON.stringify(data, null, 2));
+        }
+        else {
+            out(result.text);
+        }
+        return result.ok === false ? 1 : 0;
+    }
+    catch (e) {
+        if (e instanceof UserError || errorCode(e)?.startsWith('ERR_PARSE_ARGS')) {
+            err(`Error: ${e.message}`);
+            return 1;
+        }
+        throw e;
+    }
+}

package/dist/src/commands/init.d.ts

@@ -0,0 +1,13 @@
+import { type AgentName } from '../generate/targets.js';
+import type { CommandResult } from '../core/types.js';
+export declare const initHelp: string;
+export interface InitOptions {
+    cwd: string;
+    dir?: string | undefined;
+    withFolders?: string[];
+    language?: string | undefined;
+    /** Agents to connect. Default: Copilot. An empty list generates no agent files. */
+    agents?: AgentName[] | undefined;
+    version: string;
+}
+export declare function init({ cwd, dir, withFolders, language, agents, version }: InitOptions): CommandResult;

package/dist/src/commands/init.js

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { stringify } from 'yaml';
+import { CORE_FOLDERS, OPTIONAL_FOLDERS, PROFILE_FILE, PROFILE_ID, loadProfile } from '../core/profile.js';
+import { regenerateIndexes } from '../wiki/indexer.js';
+import { requiredPages, testingStrategyPage } from '../generate/templates.js';
+import { writeAgentFiles } from '../generate/agents.js';
+import { AGENT_NAMES, AGENT_TARGETS, DEFAULT_AGENTS } from '../generate/targets.js';
+import { findWikiRoot } from '../wiki/root.js';
+import { UserError, toPosix, writeText } from '../core/util.js';
+export const initHelp = `okfcli init [folder] [--with features,modules] [--language en] ${AGENT_NAMES.map((n) => `[--${n}]`).join(' ')} [--no-agents]
+
+Creates a wiki with the base profile core (in ./wiki by default) and the files
+that connect it to your coding agents, relative to the current directory:
+  a pointer block to the wiki in the instructions file the agent loads
+  okf-consult-wiki, okf-update-wiki, okf-review-wiki skills (consult, update and review the wiki)
+
+Pass the agents you use; without any flag it connects ${DEFAULT_AGENTS.join(', ')}:
+${AGENT_NAMES.map((n) => `  --${n.padEnd(10)} ${AGENT_TARGETS[n].instructions[0]} + ${AGENT_TARGETS[n].skillsDir}/`).join('\n')}
+Flags can be combined (okfcli init --claude --codex). okfcli never deletes
+files, so files of an agent you stop passing stay where they are.
+
+Run it again in a project that already has a wiki to refresh those files (for
+example after upgrading okfcli). It never touches the wiki pages.
+  --with       optional folders to create now: ${OPTIONAL_FOLDERS.map((f) => f.name).join(', ')}
+  --language   language of the wiki content, informational only (default: en)
+  --no-agents  do not generate the agent files`;
+function findExisting(cwd, dir) {
+    if (dir !== undefined) {
+        const root = resolve(cwd, dir);
+        return existsSync(join(root, PROFILE_FILE)) ? root : null;
+    }
+    try {
+        return findWikiRoot(cwd);
+    }
+    catch {
+        return null;
+    }
+}
+function createWiki(root, withFolders, language) {
+    const known = new Map(OPTIONAL_FOLDERS.map((f) => [f.name, f]));
+    for (const name of withFolders) {
+        if (!known.has(name)) {
+            throw new UserError(`"${name}" is not an optional folder. Options: ${[...known.keys()].join(', ')}.`);
+        }
+    }
+    const profileText = `# okfcli profile of this wiki. See https://github.com/lucasdeprit/okfcli/blob/main/SPEC.md\n${stringify({ profile: PROFILE_ID, language, extra_folders: [] })}`;
+    writeText(join(root, PROFILE_FILE), profileText);
+    const created = [PROFILE_FILE];
+    for (const folder of [...CORE_FOLDERS, ...withFolders.map((n) => known.get(n))]) {
+        mkdirSync(join(root, folder.name), { recursive: true });
+        created.push(`${folder.name}/`);
+    }
+    for (const page of [...requiredPages(), testingStrategyPage()]) {
+        writeText(join(root, page.path), page.text);
+        created.push(page.path);
+    }
+    created.push(...regenerateIndexes(root, loadProfile(root)));
+    return created;
+}
+export function init({ cwd, dir, withFolders = [], language = 'en', agents = DEFAULT_AGENTS, version }) {
+    const existing = findExisting(cwd, dir);
+    if (existing && withFolders.length) {
+        throw new UserError('A wiki already exists here: --with only applies when creating one. Add folders by creating pages with "okfcli new".');
+    }
+    const root = existing ?? resolve(cwd, dir ?? 'wiki');
+    const wikiRel = toPosix(relative(cwd, root)) || '.';
+    const created = existing ? [] : createWiki(root, withFolders, language);
+    const agentFiles = agents.length ? writeAgentFiles({ projectRoot: cwd, wiki: wikiRel, profile: loadProfile(root), version, agents }) : [];
+    const lines = [];
+    if (existing)
+        lines.push(`A wiki already exists in ${wikiRel}; its pages were not touched.`);
+    else
+        lines.push(`Wiki created in ${wikiRel}`, ...created.map((c) => `  ${c}`));
+    if (agentFiles.length)
+        lines.push('', 'Agent files:', ...agentFiles.map((f) => `  ${f.status.padEnd(9)} ${f.path}`));
+    return { root, created, agent_files: agentFiles, text: lines.join('\n') };
+}

package/dist/src/commands/new.d.ts

@@ -0,0 +1,10 @@
+import type { CommandResult } from '../core/types.js';
+export declare const newHelp = "okfcli new <type> <name> --description \"...\" [--title \"...\"]\n\nCreates a page with frontmatter and a section skeleton, and registers it in\nthe index.md of its folder. The name is relative to the folder of the type\n(e.g. \"state-management\" or \"ui/forms\"). The type is the singular name: overview, architecture, pattern, convention, workflow,\ntesting, feature, module, interface, operation, troubleshooting.";
+export interface NewPageOptions {
+    root: string;
+    type: string;
+    name: string;
+    title?: string | undefined;
+    description?: string | undefined;
+}
+export declare function newPage({ root, type, name, title, description }: NewPageOptions): CommandResult;