{
  "markdown": "# Dokion\n\n> **Execution control for user-authored engineering Playbooks**\n>\n> Dokion preserves declared order, permissions, approvals, state, evidence, verification boundaries, and repair decisions without selecting capabilities for the user\n\n[![Bun Baseline](https://img.shields.io/badge/bun-v1.3.14-black.svg?style=flat&logo=bun)](https://bun.sh)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Release Line](https://img.shields.io/badge/release-0.3.x-green.svg)](https://github.com/imMamdouhaboammar/dokion)\n\n> Current release line: `0.3.x`\n>\n> Runtime baseline: M0-M6 implemented\n>\n> Audited runtime baseline: [`docs/architecture/current-baseline.md`](docs/architecture/current-baseline.md)\n>\n> Production hardening backlog: in progress\n>\n> Compatibility matrix: [`docs/compatibility.md`](docs/compatibility.md)\n>\n> Federated Playbook Registry: protocol work in progress under [Issue #47](https://github.com/imMamdouhaboammar/dokion/issues/47)\n\n## Current truth boundary\n\nThe built-in runtime and user-authored Playbooks are available\n\nThe runtime can validate and execute the active `.dokion/playbook.json`, preserve ordered state, record findings and evidence, enforce declared approvals and write scopes, resume supported runs, and verify repair transactions where the active Playbook declares the required commands and policies\n\nRegistry package building, read-only package verification, and digest-anchored artifact pull into an immutable cache are implemented. Registry installation, activation, publishing, and Store behavior are unavailable\n\nThe replacement Registry is being built as a federated, content-addressed protocol under [Issue #47](https://github.com/imMamdouhaboammar/dokion/issues/47)\n\nThe guided Secure Release Pack, exact proposal activation flow, and versioned Run Trace are planned under [Issue #54](https://github.com/imMamdouhaboammar/dokion/issues/54). They are not current release features\n\n`dokion verify` independently re-runs every supported declared `step.verification` command and every release gate against the current repository identity. It writes fresh bounded evidence and updates verification results in `.dokion/state.json` without executing capability commands or applying repairs\n\n## What Dokion controls\n\nA Skill, tool, scanner, or agent adapter provides a capability\n\nA Dokion Playbook is the user-authored execution contract that declares:\n\n- Capability identity and source\n- Step and stage order\n- Read, write, shell, and network permissions\n- Approval boundaries\n- Failure and retry policy\n- Verification commands and release conditions\n- Applicability and coverage assignments\n\nDokion executes only the active Playbook. It does not infer a replacement capability, widen permissions, reorder steps, or install an undeclared dependency\n\n## Authority model\n\n`dokion.json` is an inert catalog\n\n`.dokion/playbook.json` is the sole execution authority\n\nThe user controls capability selection, execution order, write scope, commands, approvals, and required gates\n\nThe runtime is designed to fail closed when authority, evidence, repository identity, or persisted state cannot be verified\n\nPlatform guarantees differ by adapter and host. Read [`docs/compatibility.md`](docs/compatibility.md) before relying on hooks, process isolation, subagent behavior, or operating-system support\n\n## Installation\n\nDokion uses Bun `1.3.14` or later\n\n```bash\nbun add --global dokion@0.3.0\n```\n\nProject-local installation:\n\n```bash\nbun add --dev dokion@0.3.0\n```\n\nGit is required for repository identity, worktree policy, repair snapshots, and rollback checks\n\nPython is used by repository maintainers for schema conformance checks. It is not required for every installed CLI operation\n\n## Current quickstart\n\nInitialize Dokion-owned state:\n\n```bash\ndokion init\n```\n\n`dokion init` creates Dokion-owned state and `HARDENING.md`. It does not create or activate `.dokion/playbook.json`\n\nChoose and review a Playbook yourself, then copy the exact approved file to the sole execution-authority path:\n\n```bash\nmkdir -p .dokion\ncp /path/to/reviewed-playbook.json .dokion/playbook.json\n```\n\nThe source path is intentionally user-controlled. Review the Playbook's capabilities, commands, permissions, approvals, and verification gates before copying it\n\nInspect the project and local prerequisites:\n\n```bash\ndokion inspect\ndokion doctor\n```\n\nValidate the active Playbook and repository contracts:\n\n```bash\ndokion validate\n```\n\nPreview declared order and permissions without executing steps:\n\n```bash\ndokion plan\n```\n\nExecute through the production engine:\n\n```bash\ndokion run\n```\n\nRe-run the active Playbook's declared verification commands and release gates without applying repairs:\n\n```bash\ndokion verify\n```\n\nInspect recorded state and evidence:\n\n```bash\ndokion status\ndokion findings\ndokion report\n```\n\nResume only when the persisted state and repository identity remain valid:\n\n```bash\ndokion resume\n```\n\n## Verification and rollback scope\n\nVerification commands run as part of the declared execution path and can be re-run independently with `dokion verify`\n\nEach independent verification attempt executes the active Playbook's supported declared `step.verification` commands in stage and step order, evaluates declared release gates, binds the result to the current repository identity, and stores fresh evidence under `.dokion/evidence/`\n\nA repair is accepted only when its declared command succeeds, its delta remains in scope, suppression and test-deletion checks pass, required regression evidence exists, and declared verification commands succeed\n\nRollback applies to supported repair transactions with a captured pre-repair snapshot. Dokion does not claim that every command, every Playbook step, or every external side effect is automatically reversible\n\n`dokion verify` does not infer missing gates, execute capability commands, apply repairs, install dependencies, or widen Playbook permissions\n\nDeclared verification commands may create build, test, cache, or report artifacts allowed by the Playbook. Dokion records its own state and evidence but does not classify those declared command effects as repairs\n\n## CLI status\n\nImplemented command status is derived from `src/cli/command-registry.ts`\n\nImportant current commands:\n\n```text\nObserve\n  dokion inspect\n  dokion doctor\n  dokion status\n  dokion findings\n  dokion report\n  dokion audit\n  dokion compare\n\nConfigure\n  dokion init\n  dokion plan\n  dokion configure\n  dokion validate\n  dokion create\n  dokion playbooks\n  dokion registry\n\nExecute and decide\n  dokion run\n  dokion step\n  dokion resume\n  dokion verify\n  dokion approve\n  dokion reject\n  dokion skip\n  dokion autopilot\n```\n\nRun `dokion --help` for the registry-derived command list\n\n## Registry status\n\nImplemented:\n\n- Deterministic package construction\n- Read-only package verification\n- Local, bounded HTTPS, and pinned Git source policy\n- Digest verification\n- Immutable content-addressed cache publication\n- Cache-hit re-verification\n\nUnavailable:\n\n- Package installation\n- Lockfile mutation through pull\n- Package activation\n- Registry publishing\n- Ratings, rankings, download metrics, or trust scores\n\nRegistry metadata grants no selection, installation, activation, substitution, or execution authority\n\n## Agent adapters\n\nPackaged adapters currently exist for Claude Code, Codex, and Gemini CLI\n\nPackaging does not imply identical platform guarantees. Adapter-specific degradations are recorded and documented in [`docs/compatibility.md`](docs/compatibility.md)\n\nCursor, AGY, and other environments must not be treated as tested merely because they can read generic repository instructions\n\n## GitHub Action status\n\nThe root composite `action.yml` is an experimental repository integration until its release-candidate workflow passes on the exact tagged commit\n\nIt requires the canonical active authority file at `.dokion/playbook.json`, uses supported CLI syntax only, and does not accept another Playbook path as runtime authority\n\nDo not describe the Action as release-proven until the corresponding workflow and package checks pass for the release candidate\n\n## Contributing\n\n```bash\nbun install --frozen-lockfile\nbun run validate:contracts\nbun run test\nbun run typecheck\nbun run build\nbun run validate:distribution\nbun run smoke:package\n\ncd frontend\nbun install --frozen-lockfile\nbun run test\nbun run lint\nbun run build\ncd ..\n```\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), and the accepted architecture decisions under [`docs/adr/`](docs/adr/)\n\n## License\n\nMIT © [Mamdouh Aboammar](https://github.com/imMamdouhaboammar). See [`LICENSE`](LICENSE)\n",
  "bytes": 8675,
  "sha": "fbb29e2116dfc1b958f9e3b9173bec1c83cf82579f60a8a204e9ef2b67e4fb95",
  "repo_slug": "immamdouhaboammar/dokion",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_immamdouhaboammar_dokion_addb8eee/readme"
}