Skip to content

Expand README and split into English/Chinese editions - #17

Merged
oratis merged 1 commit into
mainfrom
claude/github-readme-docs-162e92
Aug 2, 2026
Merged

Expand README and split into English/Chinese editions#17
oratis merged 1 commit into
mainfrom
claude/github-readme-docs-162e92

Conversation

@oratis

@oratis oratis commented Aug 1, 2026

Copy link
Copy Markdown
Owner

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 primary
README.md; the Chinese edition moves to README.zh-CN.md, cross-linked from both. The two
files keep 1:1 section parity (18 ## sections each) so they can be reviewed and updated
together.

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:

  • CLI — all 8 subcommands, the global --state-dir, --isolation resolution semantics,
    and the 0/2/3 exit codes of hardware check.
  • HTTP API — all 7 endpoints, all 7 error codes, the deny_unknown_fields rejection
    behavior, and the exact scope of the Host-header DNS-rebinding defense.
  • Core model — risk levels and 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, the 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 raised into a > [!WARNING] alert.
  • CI — what each of the two workflows actually gates on.

Real output, not fabricated samples

The JSON blocks are captured from actual runs of hardware probe, hardware check,
task create-inspection, and task evaluate against a locally built binary. Paths in the
task samples are shortened for readability; field structure and values are unmodified. The
hardware check sample happens to show effective_tier: blocked on 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: Ready is not authorization to
execute; --isolation is not a sandbox proof; Host validation is not authentication; probing
is 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

  • All 41 repo-relative links in both files resolve to existing paths (scripted check).
  • Section parity confirmed: 18 ## headings in each file, same order.
  • No code or config touched — the diff is README.md and the new README.zh-CN.md only.

🤖 Generated with Claude Code

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>
@oratis
oratis merged commit 61bd48a into main Aug 2, 2026
4 checks passed
@oratis
oratis deleted the claude/github-readme-docs-162e92 branch August 2, 2026 04:22
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