docs: rewrite AGENTS.md for the post-Go, Rust-only codebase#80
Merged
Conversation
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
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AGENTS.mdwas 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 atcli/cmd/andcli/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:
pcr-core/pcr-cli/pcr-napi, pointing atNPM-INTERNALS.mdfor the napi rationale (load Rust addon intonode.exeto avoid AppLocker).auth.json,projects.json,drafts.dbschema,content_hash, exit codes), but reframed as "don't break what's already on disk" rather than "match Go".screens/vswidgets/layout, theme tokens, theHeaderBar { user: auth::load()... }pattern (so we stop hard-codinguser: Nonelike inshow.rs/help.rs), modal cancel / confirm rules, and the narrow-columnWrap { trim: false }rule we hit while fixing the empty-bundles hint.path_norm::canonicalize_project_path_cacherequirement.cargo fmt --check,cargo clippy -- -D warnings) so the next contributor doesn't tag a release that dies inlint(as just happened with v0.2.6 → re-tag).RELEASING.mdfor the full release flow.No code changes; this is a contributor-facing rewrite only.
Test plan
NPM-INTERNALS.mdworks, 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.cli/cmd/,cli/internal/, "the Go implementation", or "during the transition".Made with Cursor