AGENTS.md

1# Repository Agent Guide
2 
3## Scope
4 
5These rules apply to the complete `grok-keysmith` repository. The project is a
6zero-runtime-dependency Python CLI that manages global Grok Build instruction,
7compatibility, hook, manifest, and recovery state under `~/.grok`.
8 
9## Release and External State
10 
11- Public repository history starts at `v0.1.1`; do not import refs, commit IDs,
12  tags, or metadata from the earlier private-only predecessor.
13- Keep existing public version tags unchanged: do not move, recreate, or
14  overwrite them.
15- Verify repository visibility, tags, Releases, assets, and settings live
16  before documenting external state; a Git tag is not a GitHub Release.
17- Creating a Release, workflow, repository setting, or other external
18  publication action requires task-specific user approval.
19 
20## Change Boundaries
21 
22- Preserve preview-first behavior. Deploy, uninstall, restore, and recovery
23  writes require explicit `--yes`; `--status` remains read-only.
24- Do not test write paths against the real `~/.grok`. Use an isolated temporary
25  `HOME` and retain failure evidence until the test completes.
26- Preserve fail-closed ownership checks for manifests, backups, hooks, config
27  markers, journals, and immutable intent data.
28- Do not patch Grok binaries, intercept network traffic, manage credentials, or
29  alter running Grok processes.
30- Treat `examples/grok-unrestricted.md`, `BUNDLED_PROMPT_B64`, and
31  `BUNDLED_PROMPT_SHA256` as one versioned unit. Any prompt change must update
32  all three byte-for-byte and update README, CHANGELOG, and SECURITY hashes.
33- Keep Python 3.8 compatibility and standard-library-only runtime behavior
34  unless a versioned compatibility change is explicitly approved.
35 
36## Documentation Rules
37 
38- Keep the verified distribution boundary accurate. Do not describe a Git tag
39  as a GitHub Release or claim downloadable assets without live evidence.
40- README is bilingual: Simplified Chinese is the complete primary guide and
41  English is the concise equivalent. Keep commands, hashes, limitations, and
42  file paths aligned across both sections.
43- `CHANGELOG.md` records versioned user-visible changes. `SECURITY.md` owns
44  coordinated vulnerability reporting, rollback, prompt integrity, and
45  sensitive-data guidance.
46- Do not put credentials, tokens, cookies, private configuration, or complete
47  local user paths in tracked files or examples.
48 
49## Verification
50 
51Before committing implementation or prompt changes:
52 
531. Parse `grok-keysmith.py` with Python 3.8-compatible syntax.
542. Confirm `VERSION`, `VERSION` in Python, and documented version agree.
553. Decode `BUNDLED_PROMPT_B64` and compare it byte-for-byte with
56   `examples/grok-unrestricted.md`.
574. Confirm the decoded prompt SHA-256 equals `BUNDLED_PROMPT_SHA256` and the
58   hashes documented in README and SECURITY.
595. Run `--version`, then exercise `--status` and `--dry-run` under an isolated
60   temporary `HOME`.
616. Run `git diff --check` and inspect the complete intended diff.
62 
63Do not claim a committed test suite, CI result, Windows support, or Release
64asset verification unless the repository actually contains that evidence.
65