docs: consolidate repository documentation map
ober
b01db1b6981cd4ca70fe631544d6afe0c6937ec4
--- a/README.md +++ b/README.md @@ -114,6 +114,19 @@ repository. Stable language, library, build, and security references live at top-level `docs/`; dated audits and review records live under [`docs/reviews/`](docs/reviews/). +The shortest path through the docs is: + +- New users: [`docs/quickstart.md`](docs/quickstart.md), then + [`docs/JERBOA-LANG.md`](docs/JERBOA-LANG.md). +- Library users: [`docs/libraries.md`](docs/libraries.md), then the module + family docs linked from it. +- Security and release reviewers: + [`docs/security-reference.md`](docs/security-reference.md), + [`docs/release-security.md`](docs/release-security.md), and + [`docs/status.md`](docs/status.md). + [`docs/kimi3-security-recommmendations.md`](docs/kimi3-security-recommmendations.md) + is the active backlog, not the reference for implemented behavior. + ## Examples ### Persistent HAMT Map --- a/SECURITY.md +++ b/SECURITY.md @@ -8,11 +8,13 @@ library or developer tooling work. Implemented security behavior is documented in [`docs/security-reference.md`](docs/security-reference.md). Production claims require the gates in [`docs/release-security.md`](docs/release-security.md) -and the cross-repository tracker at `~/mine/jerboa-production-readiness.md`. +and the current repository status in [`docs/status.md`](docs/status.md). Repeatable AI-assisted adversarial review follows [`docs/security-red-team.md`](docs/security-red-team.md). The prioritized security backlog and implementation handoff lives in [`docs/kimi3-security-recommmendations.md`](docs/kimi3-security-recommmendations.md). +Use [`docs/index.md`](docs/index.md) as the canonical map when a security topic +appears in multiple docs. ## Supported Status --- a/docs/index.md +++ b/docs/index.md @@ -10,19 +10,40 @@ use the `jerboa` CLI: run programs with `jerboa run file.ss`, open the REPL with Start with [quickstart.md](quickstart.md), then use [JERBOA-LANG.md](JERBOA-LANG.md) as the language reference. +## Canonical Reading Paths + +- New language users: [quickstart.md](quickstart.md) -> + [tutorial.md](tutorial.md) -> [JERBOA-LANG.md](JERBOA-LANG.md). +- Library users: [libraries.md](libraries.md) -> topic docs such as + [concurrency.md](concurrency.md), [data-structures.md](data-structures.md), + [regex.md](regex.md), and [packages.md](packages.md). +- Runtime and compiler contributors: [build.md](build.md) -> + [native-rust.md](native-rust.md) -> [ffi.md](ffi.md) -> + [chez-hardening.md](chez-hardening.md). +- Security and release reviewers: + [security-reference.md](security-reference.md) -> + [release-security.md](release-security.md) -> [status.md](status.md) -> + [kimi3-security-recommmendations.md](kimi3-security-recommmendations.md). + ## How To Use This Map This page is the canonical documentation table of contents for the language repository. Stable user-facing language and library docs live at the top level -of `docs/`. Security implementation claims live in -[security-reference.md](security-reference.md), while dated audits, threat -reviews, and handoff notes live under `docs/reviews/` or in the explicit -backlog [kimi3-security-recommmendations.md](kimi3-security-recommmendations.md). +of `docs/`. Current production-readiness state lives in +[status.md](status.md). Implemented security claims live in +[security-reference.md](security-reference.md). Dated audits, threat reviews, +and handoff notes live under `docs/reviews/` or in the explicit backlog +[kimi3-security-recommmendations.md](kimi3-security-recommmendations.md). When a topic has both a reference and a review note, prefer the reference for current behavior and use the review note only for historical context or open work. +Design notes such as [harden.md](harden.md), [hide.md](hide.md), +[unification.md](unification.md), and [ai-threat.md](ai-threat.md) are not +release claims by themselves. They are background unless a current reference +or status document links them as implemented behavior. + ## Getting Started - [quickstart.md](quickstart.md) - install, run a file, use the REPL, run tests @@ -70,17 +91,25 @@ work. ## Security +Current references: + - [security-reference.md](security-reference.md) - canonical reference for implemented security features, gates, and current limitations -- [security-red-team.md](security-red-team.md) - repeatable AI-assisted red-team review protocol -- [kimi3-security-recommmendations.md](kimi3-security-recommmendations.md) - prioritized security backlog and implementation handoff - [safety-guide.md](safety-guide.md) - practical secure-application guide for Jerboa programs - [release-security.md](release-security.md) - release gates and security evidence -- [reviews/2026-07-27-vendor-jsqlite-tcb.md](reviews/2026-07-27-vendor-jsqlite-tcb.md) - accepted-risk review for the vendored SQLite-compatible engine -- [reviews/2026-07-27-native-export-review.md](reviews/2026-07-27-native-export-review.md) - native Rust export/caller review, zero-caller decisions, and drift gate - [capability.md](capability.md) - object-capability model - [limits.md](limits.md) - resource limits, sandboxing, and capability primitives -- [harden.md](harden.md) - binary hardening for release artifacts - [harden-usage.md](harden-usage.md) - antidebug, seccomp, integrity, and related APIs + +Backlog, audit, and review records: + +- [kimi3-security-recommmendations.md](kimi3-security-recommmendations.md) - prioritized security backlog and implementation handoff +- [security-red-team.md](security-red-team.md) - repeatable AI-assisted red-team review protocol +- [reviews/2026-07-27-vendor-jsqlite-tcb.md](reviews/2026-07-27-vendor-jsqlite-tcb.md) - accepted-risk review for the vendored SQLite-compatible engine +- [reviews/2026-07-27-native-export-review.md](reviews/2026-07-27-native-export-review.md) - native Rust export/caller review, zero-caller decisions, and drift gate + +Design background: + +- [harden.md](harden.md) - binary hardening design notes for release artifacts - [hide.md](hide.md) - reducing information leakage from binaries - [unification.md](unification.md) - security-first system architecture - [ai-threat.md](ai-threat.md) - AI-assisted adversary assessment