{
  "markdown": "# feynman\n\n![CI](https://github.com/apolenkov/feynman/actions/workflows/ci.yml/badge.svg?label=CI&color=2563EB)\n![npm](https://img.shields.io/npm/v/@albinocrabs/feynman?color=2563EB)\n![License](https://img.shields.io/github/license/apolenkov/feynman?color=2563EB)\n[![skills.sh](https://skills.sh/b/apolenkov/feynman)](https://skills.sh/apolenkov/feynman)\n\nfeynman adds visual-explanation instructions to Codex. The native skill guides\nCodex through extracting relationships from text, choosing a readable layout,\nand checking the finished diagram against the supplied facts. An optional\nlocal CLI installs session-wide diagram guidance and provides an ASCII linter.\n\nUse it when you want a visual explanation. The earlier controlled comparison\ndid not establish clearer answers than ordinary Codex responses and exhibited\nfactual and instruction-compliance failures. See the historical\n[evaluation report](docs/evaluation-3ab9de4.md). Technical test results do not\nestablish explanation quality.\n\n## Install\n\n### Native Codex plugin\n\n```bash\ncodex plugin marketplace add apolenkov/feynman --ref main\ncodex plugin add feynman@feynman\n```\n\nOpen `/plugins` in Codex to search for **Feynman**, install it, then start a\nnew session. The skill is discoverable for visual architecture, ASCII diagrams,\nflows, trees, comparisons, priorities, and status summaries.\nExplanation requests work directly from the packaged skill; they do not need\nthe CLI, a hook, network access, or local state setup.\n\n### skills.sh (Codex)\n\nFor teams that distribute skills through [skills.sh](https://www.skills.sh/),\ninstall the same Codex-only skill directly from this repository:\n\n```bash\nnpx skills add apolenkov/feynman --skill feynman --agent codex --global --yes\n```\n\nThe skill delegates state changes to the published CLI through `npx`; it does\nnot install or configure any non-Codex integration. The skills.sh catalog is\nindexed asynchronously after installations, so a newly released source can\ntake a short time to appear in search.\n\n### Local hook and CLI\n\n```bash\nnpx -y @albinocrabs/feynman@latest install\nnpx -y @albinocrabs/feynman@latest doctor\n```\n\nThe installer targets Codex by default and writes only to `~/.codex`. It is\nidempotent. Uninstall with:\n\n```bash\nnpx -y @albinocrabs/feynman@latest uninstall\n```\n\nThe native plugin supplies the Codex skill. The CLI installer registers the\n`SessionStart` hook that injects the selected ruleset into a session.\nAfter installing or updating the hook, open `/hooks` in Codex, review and trust\nits current definition, then start a new session. Codex skips new or changed\nhooks until they are trusted. This step applies to the optional hook; standalone\nskill explanations need no hook setup.\n\n## What it does\n\nThe instructions separate meaning from layout: preserve entities, relationship\nverbs, conditions and uncertainty, then choose a flow, graph, hierarchy, table\nor list. Whole-text transformations must retain every in-scope fact. Shared\nnodes and cycles need explicit connections; a tree is reserved for a hierarchy.\nDiagrams use the requested width, or 80 display columns by default.\n\nAn explicit diagram request takes precedence over automatic style limits;\nprose-only requests remain prose. Model compliance is not guaranteed. The\ndefault hook Intensity is `full`; `lite` and `ultra` are available through\n`feynman state`. These persistent preferences apply to the CLI-installed hook;\nstandalone skill explanations follow their packaged instructions and your request.\n\n```text\n[Build] --> [Test] --> [Deploy]\n```\n\nThe hook runs on `startup`, `resume`, `compact`, and `clear`, so the rules are\nrestored after context compaction without being repeated on every prompt.\n\n## CLI\n\n```bash\nfeynman install             # register the Codex hook\nfeynman doctor              # inspect the local Codex installation\nfeynman state lite          # set diagram intensity\nfeynman state style short   # choose an output-style preset\nfeynman status              # show current state\nfeynman uninstall           # remove feynman registration, keep state\nfeynman lint README.md      # lint ASCII visuals in a file\nfeynman lint --strict FILE  # treat warnings as errors\nfeynman examples            # list bundled examples\nfeynman bootstrap --out DIR # export an operable local bundle\nfeynman version\n```\n\nThe CLI has zero third-party runtime dependencies and requires Node.js 22.18 or\nnewer. Installation through `npx` still requires npm. The native explanation\nskill does not need Node.js until you explicitly request a CLI operation.\n\n`bootstrap --force` replaces only a previous Feynman export with ownership\nmetadata. It refuses unrelated, symlinked and protected destinations.\n\n## Repository map\n\n```text\ncore contract       rules/, lib/state/     Contract, state model, pure rules\napplication         bin/commands/          CLI use cases\nadapters            bin/adapters/, hooks/  Codex filesystem and SessionStart integration\nlint subsystem      lib/lint/              parser, rules, reporter\nquality             tests/, scripts/       tests, checks, package build\nCodex distribution  plugins/feynman/       native marketplace plugin\ndocumentation       docs/, CONTEXT.md      architecture, decisions, vocabulary\nspecifications      openspec/specs/        active testable requirements\n```\n\nThe core contract never depends on commands or adapters; commands coordinate\nthe local Codex/filesystem adapters. The linter is a separate application path\nsharing only small domain-neutral utilities. See\n[Architecture](docs/architecture.md) for the full map and boundaries.\n\n## Development\n\n```bash\ngit clone https://github.com/apolenkov/feynman.git\ncd feynman\nnpm ci\nnpm run ci\n```\n\nBefore opening a pull request, run `npm run ci` and lint each changed Markdown file\nwith `npm run lint -- <file.md>`. Use Conventional Commits. Keep changes focused and\nadd a test for changed behavior.\n\nThe quality gate checks formatting, types, typed lint, behavior, coverage scope,\ndocumentation and byte-for-byte package reproducibility. The live comparison\nof explanations is separate: the latest 96-answer experiment completed and\nfailed its acceptance criteria. See the [results](docs/evaluation-3ab9de4.md)\nand [protocol](evals/protocol-v2.md).\nThe new [ASCII transformation protocol](evals/ascii-transformation-protocol.md)\ntests complete fact preservation and readable relationships through the actual\ndelivery paths. Its [research rationale](docs/ascii-explanation-research.md)\ndistinguishes these checks from unproven claims about human reading speed.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow,\n[SECURITY.md](SECURITY.md) for private vulnerability reports, and\n[docs/release.md](docs/release.md) for publishing. See\n[docs/codex-plugin.md](docs/codex-plugin.md) for the native plugin contract.\n\n## Privacy and license\n\nfeynman is local-only: its hook reads packaged rules and Codex-local state and\nwrites no telemetry. A skill-requested `npx` state command may fetch the public\npackage if it is not already cached; the hook itself makes no network request.\nSee [PRIVACY.md](PRIVACY.md). Licensed under the MIT License.\n",
  "bytes": 7158,
  "sha": "ef31ec6e1b15acf037f18eccfe601bba9c6ae26873b57da155d208fc8a716be1",
  "repo_slug": "apolenkov/feynman",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_apolenkov_feynman_feynman_01ff63ff/readme"
}