Skip to content

docs: README and command pages use current paths and facts (C4.1, CORE-174) - #417

Merged
PrzemekGalarowicz merged 3 commits into
mainfrom
przemek/core-174-docs-current-paths
Nov 17, 2026
Merged

PrzemekGalarowicz merged 3 commits into
mainfrom
przemek/core-174-docs-current-paths

Conversation

@PrzemekGalarowicz

@PrzemekGalarowicz PrzemekGalarowicz commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Linear: CORE-174 (epic CORE-153). Docs-only except item 15 (the --help header, with an [Unreleased] CHANGELOG line and a test assertion).

Checklist (ticket items)

  • 1. SPEC template path — README now says pharn/spec-template.md (verified in pharn-oss 7.22.0: protect-trusted-paths.cjs, pharn/floor/spec-template-core.mjs). The root-migration part is moot (refactor: remove the flat layout and the root migration (CORE-155) [v0.21.0] #412 removed it): the README's root-footprint paragraph now says a root pharn.spec-template.md/memory-bank/ is never moved or mentioned and you git mv it yourself; the stale "pharn update prints the replacement .pharn/ line" sentence is corrected too.
  • 2. memory-bank/ → pharn/memory-bank/ — README (two places), docs/getting-started.md, docs/commands/remove.md (verified in 7.22.0's pharn-memory-promote.md).
  • 3. Write guard paths — README uses pharn/.run/**, pharn/.run/<command>/<name>/active.json, pharn/.run/writes-scope.json (verified against the installed 7.22.0 enforce-writes-scope.cjs, not this repo's own hooks).
  • 4. Trusted docs at the root — already fixed on main (init.md says all four land in pharn/; the "Rename yours first" text is gone). The flat-layout part is moot (refactor: remove the flat layout and the root migration (CORE-155) [v0.21.0] #412). SECURITY.md:7 is C4.4's.
  • 5. "wizard" / "asks which capabilities" — init.md header and "interactive by default" section now describe the summary + "Ready to install?" (+ the overwrite question), and point to --archetype / add / remove for selection; troubleshooting "the wizard cancels" → "pharn init cancels".
  • 6. "init has no --yes" — fixed in update.md and reference/pharn-config.md, linking init's --yes section.
  • 7. "remove the archetype that selects it" — remove.md now says there is no permanent exclusion, universal is selected regardless, and only pharn init --archetype <list> changes archetypes; new Planned roadmap row "Permanent capability exclusion".
  • 8. Legacy entries "inferred as manual" — list.md: selected → auto, unselected → manual (rows 4/8 of merge-capabilities.ts).
  • 9. features/README.md "in both layouts" — already fixed on main (getting-started.md says pharn/features/README.md); the flat half is moot (refactor: remove the flat layout and the root migration (CORE-155) [v0.21.0] #412).
  • 10. main framed as the default — init.md, add.md (two places), update.md, troubleshooting.md now lead with the newest verified release; --ref main is the opt-in.
  • 11. "~450 files" → "several hundred" (the real run below installed 533 recorded files for lib alone).
  • 12. Quick start git commit after create-next-app — README and getting-started run the git lines only when .git is absent: [ -d .git ] || { git init && git add -A && git commit -m "init"; }, with a sentence on why. (The shadcn step in getting-started is C4.6's; left as is.)
  • 13. Example config / records — regenerated from a real run (below); the records example now includes pharn.config.json#/models and .claude/settings.json.
  • 14. --drift — already fixed on main (status.md says --no-drift).
  • 15. Help header — src/lib/cli-args.ts now prints Options (each names the commands that take it; any other command refuses it):; pinned in tests/cli-args.test.ts; the same "exactly one command" claim in docs/troubleshooting.md is corrected; CHANGELOG [Unreleased] line added.

How the examples were generated

npm run build on this branch (rebased on the 0.21.0 release, so pharn 0.21.0), then in an empty temp dir:

git init && printf '{\n  "name": "demo",\n  "version": "1.0.0"\n}\n' > package.json
node <worktree>/dist/index.js init --yes      # fetched pharn-oss v7.22.0 (commit 9422b97f) from codeload
node <worktree>/dist/index.js add n-plus-one  # adds a manual entry

The doc blocks are that pharn.config.json and pharn.records.json, trimmed with … (models stages, most capabilities, hash tails); the command is recorded in the docs above each block.

Checks run locally

format:check, lint, lint:md, typecheck, vitest run (3595 passed).

🤖 Generated with Claude Code

@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 28 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 7c45c42 and 8d4cb5e.

Files selected for processing: 14

  • CHANGELOG.md
  • README.md
  • docs/commands/add.md
  • docs/commands/init.md
  • docs/commands/list.md
  • docs/commands/remove.md
  • docs/commands/update.md
  • docs/getting-started.md
  • docs/reference/pharn-config.md
  • docs/reference/pharn-records.md
  • docs/roadmap.md
  • docs/troubleshooting.md
  • src/lib/cli-args.ts
  • tests/cli-args.test.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

…E-174)

Bring the README and command pages in line with the code and pharn-oss 7.x:
the write guard's pharn/.run/ paths, pharn/spec-template.md,
pharn/memory-bank/, the root footprint left in place now that the
migration is gone, init's one "Ready to install?" question, init --yes,
the newest verified release as the default source, the legacy-source
inference, no permanent exclusion (a Planned roadmap row), a quick start
that does not fail after create-next-app's own commit, and example
config/records blocks regenerated from a real pharn 0.20.0 run.

`pharn --help` no longer says each option belongs to ONE command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

pharn

🛡️ pharn-ci · ✅ Pass

Tip

Pass · This change adds no coverable lines; 29 agent setup files found.

Verdict Diff coverage Test integrity Agent setup
✅ Pass no coverable lines none (block) 29 files

🧪 Diff coverage

No coverable lines changed.

🔍 Test integrity

No test-integrity findings (mode: block).

Tests changed: +0 −0 ~1
Test file Added Removed Modified Renamed
tests/cli-args.test.ts 0 0 1 0

💬 Messages (1)

  • ℹ️ NO_COVERABLE_CHANGES No added lines are tracked by the coverage report; nothing to measure.
    • Hint: Nothing to do if the change has no code; otherwise check that the coverage report includes the changed files.

🤖 Agent setup (29 files)

Agent setup: 29 files · claude-code

Agent setup files (29)
Path Kind
.claude/commands/pharn-dev-build.md claude-command
.claude/commands/pharn-dev-eval.md claude-command
.claude/commands/pharn-dev-grill.md claude-command
.claude/commands/pharn-dev-memory-promote.md claude-command
.claude/commands/pharn-dev-plan.md claude-command
.claude/commands/pharn-dev-regress.md claude-command
.claude/commands/pharn-dev-review.md claude-command
.claude/commands/pharn-dev-ship.md claude-command
.claude/commands/pharn-dev-verify.md claude-command
.claude/hooks/enforce-writes-scope.cjs claude-hook
.claude/hooks/enforce-writes-scope.test.cjs claude-hook
.claude/hooks/git-worktree-fixture.cjs claude-hook
.claude/hooks/protect-trusted-paths.cjs claude-hook
.claude/hooks/protect-trusted-paths.test.cjs claude-hook
.claude/hooks/session-root.cjs claude-hook
.claude/hooks/session-root.test.cjs claude-hook
.claude/hooks/set-writes-scope.cjs claude-hook
.claude/hooks/set-writes-scope.test.cjs claude-hook
.claude/settings.json claude-settings
.claude/skills/phargus-diagnose claude-skill
.claude/skills/phargus-memory claude-skill
.claude/skills/phargus-rules claude-skill
.claude/skills/phargus-setup claude-skill
.claude/skills/phargus-verify claude-skill
.claude/skills/pharn-ci-cover claude-skill
.claude/skills/pharn-ci-explain claude-skill
.claude/skills/pharn-ci-install claude-skill
.claude/skills/pharn-cli claude-skill
CLAUDE.md claude-md

pharn-ci 0.10.0 · report schema v2 · coverage format lcov

…(C4.1, CORE-174)

Rebased on the 0.21.0 release: the CHANGELOG entry moves out of the
released section, and the config/records examples are regenerated from a
real 0.21.0 run (pharn init --yes, then pharn add n-plus-one).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@PrzemekGalarowicz
PrzemekGalarowicz force-pushed the przemek/core-174-docs-current-paths branch from 6f8675f to 6e23870 Compare November 17, 2026 12:16
@PrzemekGalarowicz
PrzemekGalarowicz merged commit 3e28c8b into main Nov 17, 2026
15 checks passed
@PrzemekGalarowicz
PrzemekGalarowicz deleted the przemek/core-174-docs-current-paths branch November 17, 2026 12:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant