'cargo install agent-code' installs 'agent.exe' (Windows) / 'agent'
(Unix), NOT 'agent-code'. Previous note said "binary name is 'agent-code'"
which sent users to the wrong command.
Updated the install warning to show the actual binary name.
ROADMAP #53 filed: package vs binary name mismatch in the install path.
Previous wording said 'recommended shell is Git Bash or WSL (not PowerShell,
not cmd)' which was incorrect — claw builds and runs fine in PowerShell.
New framing:
- PowerShell: supported primary Windows path with PowerShell-style commands
- Git Bash / WSL: optional alternatives, not requirements
- MINGW64 note moved to Git Bash callout (no longer implies it is required)
Source: gaebal-gajae correction 2026-04-10.
The claw-code crate on crates.io is a deprecated stub. cargo install
claw-code succeeds but places claw-code-deprecated.exe, not claw.
Running it only prints 'claw-code has been renamed to agent-code'.
Previous note only warned about 'clawcode' (no hyphen) — the actual trap
is the hyphenated name.
Updated the warning block with explicit caution: do not use
'cargo install claw-code', install agent-code or build from source.
ROADMAP #52 filed.
Users were hitting:
- bash: cargo: command not found (Rust not installed or not on PATH)
- C:\... vs /c/... path confusion in Git Bash
- MINGW64 prompt misread as broken install
New '### Windows setup' section in README covers:
1. Install Rust via rustup.rs
2. Open Git Bash (MINGW64 is normal)
3. Verify cargo --version / run . ~/.cargo/env if missing
4. Use /c/Users/... paths
5. Clone + build + run steps
WSL2 tip added for lower-friction alternative.
ROADMAP #51 filed.
The previous quick start jumped from 'cargo build' to 'claw prompt' without
showing the required auth step or the health-check command. A user following
it linearly would fail because the prompt needs an API key.
Changes:
- Numbered steps: build -> set ANTHROPIC_API_KEY -> claw doctor -> prompt
- Windows note updated to show cargo run form as alternative
- Added explicit NOTE that Claude subscription login is not supported (pre-empts #claw-code FAQ)
Source: cold-start friction observed from mezz/mukduk and kapcomunica in #claw-code 2026-04-09.
User repro: mezz on Windows PowerShell tried './target/debug/claw'
which fails because the binary is 'claw.exe' on Windows.
Add a NOTE callout after the quick-start block directing Windows users
to use .\target\debug\claw.exe or cargo run -- --help.
Repeated onboarding friction in #claw-code: users try 'cargo install clawcode'
which fails because the package is not published on crates.io. Add a prominent
NOTE callout before the quick-start block directing users to build from source.
Source: gaebal-gajae pinpoint 2026-04-09 from #claw-code.
Finish the remaining roadmap work by making direct CLI JSON output deterministic across the non-interactive surface, restoring the degraded-startup MCP test as a real workspace test, and adding branch-lock plus commit-lineage primitives so downstream lane consumers can distinguish superseded worktree commits from canonical lineage.
Constraint: Keep the user-facing config namespace centered on .claw while preserving legacy fallback discovery for compatibility
Constraint: Verification needed to stay clean-room and reproducible from the checked-in workspace alone
Rejected: Leave the output-format contract implied by ad-hoc smoke runs only | too easy for direct CLI regressions to slip back into prose-only output
Rejected: Keep commit provenance as free-form detail text | downstream consumers need structured branch/worktree/supersession metadata
Confidence: medium
Scope-risk: moderate
Directive: Extend the JSON contract through the same direct CLI entrypoints instead of adding one-off serializers on parallel code paths
Tested: python .github/scripts/check_doc_source_of_truth.py
Tested: cd rust && cargo fmt --all --check
Tested: cd rust && cargo test --workspace
Tested: cd rust && cargo clippy -p commands -p tools -p rusty-claude-cli --all-targets --no-deps -- -D warnings
Not-tested: full cargo clippy --workspace --all-targets -- -D warnings still reports unrelated pre-existing runtime lint debt outside this change set
Replace the stale Python-first README narrative, old community links, and leftover branded metadata with the current Rust-first repo guidance. Also align funding handles and asset naming so the public docs point at the canonical ultraworkers/claw-code surface.\n\nConstraint: Scope limited to docs/metadata and branding residue; no runtime behavior changes\nRejected: Add a new CI lint in this pass | outside the requested docs-and-config cleanup scope\nConfidence: medium\nScope-risk: narrow\nReversibility: clean\nDirective: Keep README, funding metadata, and community links aligned with ultraworkers/claw-code and the current UltraWorkers Discord invite\nTested: stale-branding grep across markdown/.github; root doc-link existence checks; cargo fmt --all --check; cargo check --workspace; cargo test --workspace\nNot-tested: cargo clippy --workspace --all-targets -- -D warnings | fails on pre-existing runtime lint debt unrelated to these doc changes
Add a checked-in Containerfile plus container-first documentation so Docker and Podman users have a canonical image build, bind-mount, and cargo test entrypoint. The README now links directly to the new guide.
Constraint: The repo already had runtime container detection but no checked-in Dockerfile, Containerfile, or devcontainer config
Rejected: Put all container steps inline in README only | harder to maintain and less reusable than a dedicated guide plus Containerfile
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep docs/container.md and Containerfile aligned whenever Rust workspace prerequisites change
Tested: docker build -t claw-code-dev-docs-verify -f Containerfile .
Tested: cargo test --workspace (host, in rust/)
Not-tested: Podman commands were documented but not executed in this environment
Not-tested: Repeated in-container cargo test --workspace currently trips crates/tools PowerShell stub detection on this minimal image even though host cargo test passes
The root and Rust-facing docs now point readers at a single task-oriented usage guide with build, auth, CLI, session, and parity-harness examples. This also fixes stale workspace references and updates the Rust workspace inventory to match the current crate set.
Constraint: Existing README copy still referenced the old dev/rust status and needed to stay lightweight
Rejected: Fold all usage details into README.md only | too much noise for the landing page
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep USAGE examples aligned with when CLI flags change
Tested: cargo build --workspace; cargo test --workspace
Not-tested: External links and rendered Markdown in GitHub UI
The old tracked TypeScript snapshot has been removed from the repository history and the root directory is now a Python porting workspace. README and tests now describe and verify the Python-first layout instead of treating the exposed snapshot as the active source tree.
A local archive can still exist outside Git, but the tracked repository now presents only the Python porting surface, related essay context, and OmX workflow artifacts.
Constraint: Tracked history should collapse to a single commit while excluding the archived snapshot from Git
Rejected: Keep the exposed TypeScript tree in tracked history under an archive path | user explicitly wanted only the Python porting repo state in Git
Confidence: medium
Scope-risk: broad
Reversibility: messy
Directive: Keep future tracked additions focused on the Python port itself; do not reintroduce the exposed snapshot into Git history
Tested: python3 -m unittest discover -s tests -v; python3 -m src.main summary; git diff --check
Not-tested: Behavioral parity with the original TypeScript system beyond the current Python workspace surface
