docs(readme): expand stub README to full structure

README.adoc

@@ -1,12 +1,71 @@
 // SPDX-License-Identifier: MPL-2.0
-// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
 
 = git-reticulator
 :toc: preamble
 :icons: font
+:revdate: 2026-05-26
 
 image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/git-reticulator"]
-image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
+image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"]
 image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"]
 
+Semantic-lattice builder for git repositories — derives a lattice
+representation of a repo's history (commits, files, semantic edits) and
+exposes it via a Rust API. AffineScript is the eventual frontend target.
 
+== Why this exists
+
+Existing git-analysis tools work at the raw commit/blob level. `git-reticulator`
+lifts the analysis to a **semantic lattice** — meet/join operations over
+commits, file-trajectories, and (eventually) AST-level semantic edits.
+The output is suitable for:
+
+* Refactoring-impact analysis (what changes propagate where).
+* Authorship attribution at semantic-unit granularity.
+* Time-aware queries ("when did this concept enter the codebase").
+
+== Quickstart
+
+[source,bash]
+----
+# Build:
+just build           # or: cargo build --release
+
+# Run against a local repo:
+./target/release/git-reticulator scan /path/to/repo
+
+# See available commands:
+./target/release/git-reticulator --help
+----
+
+== Architecture
+
+Written in Rust. AffineScript bindings planned in a future phase
+(currently a Rust-only library + CLI).
+
+* `src/` — core library + CLI.
+* `benches/` — benchmark harness.
+* `configs/` — example configurations for typical scan profiles.
+* `docs/` — design notes and ADRs.
+
+== Status
+
+* **Licence**: MPL-2.0. (Previously declared PMPL-1.0-or-later — migrated
+  2026-05-26 per the estate licence-debt audit, hyperpolymath/standards#196.)
+* **Maturity**: research / iteration. API not stable.
+* **Audit findings**: see `docs/tech-debt-2026-05-26.md` if present
+  (added by the 2026-05-26 estate tech-debt scan).
+
+== Contributing
+
+See link:CONTRIBUTING.md[CONTRIBUTING.md]. All commits must be GPG-signed.
+Conventional-commits required (CHANGELOG is generated by
+link:https://github.com/hyperpolymath/standards/pull/206[standards#206]'s
+`changelog-reusable.yml`).
+
+== Companion repositories
+
+* link:https://github.com/hyperpolymath/standards[`hyperpolymath/standards`] — canonical estate standards.
+* link:https://github.com/hyperpolymath/affinescript[`hyperpolymath/affinescript`] — the language whose bindings will become this repo's eventual frontend.
+* link:https://github.com/hyperpolymath/k9[`hyperpolymath/k9`] — the related metadata-extraction tooling (`k9iser.toml` is consumed here).