docs: polish README and standardise British English guides

[nonnil]

Summary

The README mixed Japanese and English and combined the product introduction with detailed operating instructions. Give it a concise, branded entry point with features, an authenticated mock quick start and a documentation table. Move the detailed content into reader, development, deployment and security guides.

Standardise maintained documentation on British English and update the documentation index and package instructions. Correct stale instructions against the current implementation: swipe down advances, the relay permits twelve operations, and the quick start now generates and supplies the gateway key. Clarify that public access requires bearer authentication in the configuration example.

Make the first-run path explicitly use the installed Even Hub simulator: the companion waits for its SDK bridge before enabling pairing, so a regular browser cannot complete setup. Include clone and runtime prerequisites, separate terminal steps, expected mock output and shutdown instructions. Set X_SOURCE=mock explicitly to avoid inheriting live mode from the shell.

Preserve main's native reader scrolling when resolving the README conflict, including bounded UTF-16 chunks, text-container creation and upgrade, position indicators and the final media frame. Update only the transitive development dependency js-yaml from 4.3.1 to 4.3.2 to clear the High-severity audit failure in CI; keep the audit threshold unchanged.

Validation

• npm ci && npm run ci passed: clean dependency installation, the High-severity audit gate, formatting, repository checks, TypeScript, 33 test files / 162 tests, all builds, production packaging and artefact checks.
• git diff --check passed.
• Checked all 13 Markdown documents for remaining Japanese prose and checked local links and anchors; the follow-up review also checked all 33 relative paths in the edited README and development guide.
• All 10 shell examples in those two documents pass sh -n. The installed simulator's --help confirms the URL argument; runtime versions and expected output match the source.
• Runtime code matches main; only documentation and the js-yaml lockfile entry differ. Manifests and legal licence text are unchanged. No complete simulator pairing, deployment or hardware validation was performed.
• Three pre-existing Moderate audit entries involving Hono and Vitest/@vitest/mocker remain; the configured High-severity gate passes.
• Production package SHA-256: 1423b8d7f6450b84340a1cacff0a23aaded16a26e57a5a057e349cc1bbb900b9 (generated package untracked).

Summary by CodeRabbit

• Documentation
  • Reorganized the project overview and added dedicated guides for reader controls, development, deployment, and security.
  • Added mock-mode setup instructions and guidance on gateway pairing, release verification, packaging, and device testing.
  • Updated documentation to use British English and clarified that a private key is required before exposing the gateway.

[capy-ai]

Capy couldn't review this pull request because h1's workspace is out of credits, add credits or enable auto-reload to resume automatic reviews.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: cd93c14e-4f3a-411e-a43b-5afacf6a1155

📥 Commits

Reviewing files that changed from the base of the PR and between f8651d6 and a5d66df.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (3)

• README.md
• docs/development.md
• docs/reader-guide.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The README now provides a project overview and quick start. Dedicated guides cover reader behavior, development, deployment, and security. Repository guidance sets British English as the convention for maintained documentation. The environment example states that a private key is required before exposing the gateway.

Changes

Documentation and operating guidance

Layer / File(s)	Summary
Project overview and documentation map README.md, docs/INDEX.md, AGENTS.md, docs/agent-harness.md	The README provides a project overview, quick start, and contribution guidance. The index and repository guidance direct readers to focused documentation and specify the maintained-documentation language convention.
Reader guide and pairing apps/g2/AGENTS.md, docs/reader-guide.md	The reader guide documents controls, media presentation, pairing, key handling, and app icon use. The G2 agent guidance links to reader and deployment documentation.
Development and preview instructions docs/development.md	The guide documents mock and live-X setup, live-device preview, verification commands, and credential and session handling.
Deployment and security guidance .env.example, apps/gateway/AGENTS.md, docs/deployment.md, docs/security.md	The guides document hosting, gateway authentication, relay and media limits, packaging, and device testing. The environment example states that a private key is required before exposing the gateway.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to a5d66

The documented mock setup has no identified blocker. Merge after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to a5d66

The revised instructions strengthen guidance to use a private key before exposing the gateway. No new security flaw was verified. Dependency installation still runs third-party code, whose exact behaviour remains unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Dependency lifecycle scripts run during the documented local install under the invoking user's authority. The new quick-start key is not yet generated at that point, but other inherited credentials or files may be accessible; the script's actual behaviour is unverified.

Security Findings and Attack Paths

• inferred — The deferred installation candidate does not establish a PR-introduced attack path: the base quick start already installed dependencies and the relevant esbuild lock entry is unchanged. Script behaviour and network destinations remain unknown.

Trust Boundaries and Controls

• observed — For gateway API requests, bearer validation depends on a configured token; permissive bearer CORS cannot be enabled without one. The revised public-deployment guidance calls for a token and keeps the relay on loopback.

Hardening Proposals

• proposed — Where installations may inherit sensitive credentials, document using a restricted development environment until dependency install-script behaviour can be verified.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main changes: updating the README and standardising British English across documentation guides.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[nonnil]

Reviewed the documentation changes against the current implementation and the latest main branch. No remaining actionable documentation regression found after resolving the issues below.

• Resolved the README conflict with main without rewriting branch history.
• Preserved main's native-scroll implementation and hardware-validation backlog verbatim. Updated the English README and reader guide to describe native scrolling, bounded UTF-16 chunks, creation followed by text upgrade, position indicators and the final media frame.
• Confirmed that the PR retains bearer-authenticated gateway guidance, loopback-only Safe Relay, user-configured pairing and the distinction between software checks and physical-device evidence.
• Fixed the CI-blocking High finding GHSA-2883-xcg3-v3hh by updating only the Even Hub CLI's transitive js-yaml dependency from 4.3.1 to 4.3.2 in the existing lockfile. No audit threshold or workflow was weakened.
• A fresh npm ci followed by npm run ci passed: the High-severity audit gate, formatting, repository invariants, TypeScript, 33 test files / 162 tests, all builds, production packaging and artefact checks.
• GitHub CI run 36332912600 passed on the final reviewed commit. GitHub reports the PR as mergeable.

Residual risk: npm audit still reports three pre-existing Moderate entries involving Hono and Vitest/@vitest/mocker. They are outside this bounded documentation and CI-blocker fix; passing the configured High-severity gate is not a clean vulnerability report.

Verified package SHA-256: 1423b8d7f6450b84340a1cacff0a23aaded16a26e57a5a057e349cc1bbb900b9. The generated package remains untracked. No deployment or physical-device validation was performed.

This review is recorded as a comment because the authenticated account is also the PR author; it does not constitute an independent GitHub approval.