Skip to content

docs: rewrite AGENTS.md for the post-Go, Rust-only codebase#80

Merged
KaluJo merged 1 commit into
mainfrom
agents-md-rust-only
Apr 26, 2026
Merged

docs: rewrite AGENTS.md for the post-Go, Rust-only codebase#80
KaluJo merged 1 commit into
mainfrom
agents-md-rust-only

Conversation

@KaluJo
Copy link
Copy Markdown
Collaborator

@KaluJo KaluJo commented Apr 26, 2026

Summary

AGENTS.md was written during the Go → Rust port and still reads like a transitional document — it tells contributors "the Go implementation under ../cli/ is the behavioral source of truth", points at cli/cmd/ and cli/internal/ directories that no longer exist, and frames everything in terms of "parity" with a build that was deleted in the rust-port merge.

This PR rewrites it as a Rust-only contributor guide and folds in the conventions that have hardened since the port:

  • Crate-shape diagram for pcr-core / pcr-cli / pcr-napi, pointing at NPM-INTERNALS.md for the napi rationale (load Rust addon into node.exe to avoid AppLocker).
  • "On-disk format stability" replaces "Parity with the Go CLI" — same byte-compatibility constraints (auth.json, projects.json, drafts.db schema, content_hash, exit codes), but reframed as "don't break what's already on disk" rather than "match Go".
  • New "TUI conventions" section: screens/ vs widgets/ layout, theme tokens, the HeaderBar { user: auth::load()... } pattern (so we stop hard-coding user: None like in show.rs / help.rs), modal cancel / confirm rules, and the narrow-column Wrap { trim: false } rule we hit while fixing the empty-bundles hint.
  • New "Source watchers" section documenting the main-thread / non-blocking invariant and the path_norm::canonicalize_project_path_cache requirement.
  • "Running locally" now lists the exact lint commands CI runs (cargo fmt --check, cargo clippy -- -D warnings) so the next contributor doesn't tag a release that dies in lint (as just happened with v0.2.6 → re-tag).
  • Pointer to RELEASING.md for the full release flow.

No code changes; this is a contributor-facing rewrite only.

Test plan

  • Read through the rendered file on GitHub — the link to NPM-INTERNALS.md works, the table renders, all referenced files (tui/screens/show.rs, auth.rs, tui/screens/status.rs, path_norm, golden.rs, etc.) actually exist at those paths.
  • No remaining mentions of cli/cmd/, cli/internal/, "the Go implementation", or "during the transition".

Made with Cursor

The Go sources were removed in the rust-port merge commit, but
AGENTS.md still framed itself as transitional ("the Go implementation
is the behavioral source of truth", "Port state", references to
`cli/cmd/` and `cli/internal/`). That's now misleading guidance for
contributors and AI assistants.

Rewrite to reflect the current state and capture conventions that
have solidified since the port:

* Crate-shape diagram for `pcr-core` / `pcr-cli` / `pcr-napi`,
  pointing at NPM-INTERNALS.md for the napi rationale.
* "On-disk format stability" replaces "Parity with the Go CLI" —
  same byte-compatibility constraints (auth.json, projects.json,
  drafts.db schema, content_hash, exit codes), but framed as
  "don't break what's already on disk" rather than "match Go".
* New "TUI conventions" section: screens vs widgets layout, theme
  tokens, the `HeaderBar { user: auth::load()... }` pattern (so we
  stop hard-coding `user: None` and rendering "not signed in"),
  modal cancel / confirm conventions, and the narrow-column
  `Wrap { trim: false }` rule we just learned the hard way.
* New "Source watchers" section documenting the
  main-thread / non-blocking invariant and the
  `path_norm::canonicalize_project_path_cache` requirement for
  project attribution.
* "Running locally" now lists the lint commands CI uses
  (`cargo fmt --check`, `cargo clippy -- -D warnings`) so the next
  contributor doesn't tag a release that dies in the lint job.
* Pointer to RELEASING.md for the full release flow.

No code changes; this is a contributor-facing rewrite only.

Made-with: Cursor
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