Expand README and split into English/Chinese editions - #17
Merged
Conversation
The README documented the project at a high level but left the shipped interfaces undocumented: readers had no reference for the CLI, the HTTP API, the risk/capability model, or the OS build and acceptance flow without reading source or docs/. It was also Chinese-only with a short English summary, which puts non-Chinese readers behind a translation step on the repository's front page. Make English the primary README and move the Chinese edition to README.zh-CN.md, cross-linked from both. The two files keep 1:1 section parity so they can be reviewed and updated together. New reference material, all verified against the source: - CLI: all 8 subcommands, the global --state-dir flag, --isolation semantics, and the 0/2/3 exit codes of `hardware check`; - HTTP API: all 7 endpoints plus the 7 error codes, the deny_unknown_fields behavior, and the exact scope of the Host-header DNS-rebinding defense; - core model: risk levels and their isolation floors, per-ActionKind risk floors and target semantics, the four capability resource kinds, the policy decision order, and a Mermaid state-machine diagram with its invariants; - durability: compaction write ordering, crash-safety guarantee, and the 10,000-action plan limit; - OS image: build, install E2E, hardware matrix, and GCP nested-KVM flows, with the destructive CI boot entry called out in an alert; - CI: what each of the two workflows gates on. JSON samples are real output captured from `hardware probe`, `hardware check`, `task create-inspection`, and `task evaluate` rather than illustrative fabrications; paths in the task samples are shortened. The project's existing boundary claims are preserved verbatim in both editions, including "Ready is not authorization to execute", that --isolation is not a sandbox proof, that Host validation is not authentication, that probing is not support, the outstanding GCP re-run, and the explicit not-implemented list. Both ISO SHA-256 values are kept in full so the evidence stays verifiable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
User outcome
A reader landing on the repository can now understand what Andromeda is, run it, and call
its shipped interfaces without reading source or
docs/first. English becomes the primaryREADME.md; the Chinese edition moves toREADME.zh-CN.md, cross-linked from both. The twofiles keep 1:1 section parity (18
##sections each) so they can be reviewed and updatedtogether.
What was missing
The previous README covered status, goals, and the crate table, but left every shipped
interface undocumented — no CLI reference, no HTTP API reference, no risk/capability model,
no OS build or acceptance flow. It was also Chinese-only with a ~15-line English summary,
putting non-Chinese readers behind a translation step on the front page.
New reference material
All of it verified against the source, not written from memory:
--state-dir,--isolationresolution semantics,and the
0/2/3exit codes ofhardware check.deny_unknown_fieldsrejectionbehavior, and the exact scope of the
Host-header DNS-rebinding defense.ActionKindrisk floors andtargetsemantics, the four capability resource kinds, the policy decision order, and a Mermaid
state-machine diagram with its invariants.
10,000-action plan limit.
destructive CI boot entry raised into a
> [!WARNING]alert.Real output, not fabricated samples
The JSON blocks are captured from actual runs of
hardware probe,hardware check,task create-inspection, andtask evaluateagainst a locally built binary. Paths in thetask samples are shortened for readability; field structure and values are unmodified. The
hardware checksample happens to showeffective_tier: blockedon an Apple silicon host,which doubles as a concrete demonstration that probing is not support.
Boundary claims preserved
This repository's documentation is deliberately conservative, and none of that was diluted for
readability. Carried through verbatim in both editions:
Readyis not authorization toexecute;
--isolationis not a sandbox proof; Host validation is not authentication; probingis not support; the outstanding one-pass GCP re-run; and the explicit not-implemented list
(executor, credential broker, verifier, signed policy bundle, remote auth). Both ISO SHA-256
values are kept in full — I had truncated them at one point and restored them, since a
truncated checksum is not verification data.
Validation
##headings in each file, same order.README.mdand the newREADME.zh-CN.mdonly.🤖 Generated with Claude Code