# 05 — Site Architecture **Status:** ✅ near-as-is · ✏️ needs framing · ✍️ write fresh · 🔗 links out · ⚠️ correction required --- ## Shape The site has two audiences with different urgencies: someone deciding whether to use Issues-FS (**navigate what ships**), and someone who wants the ideas (**teach the concepts**). Serve the first in one click. ``` issues-fs.sgit.ai ├── / what it is + the package table, above the fold ├── /start/ install → init → first graph, five minutes ├── /lite/ ★ the agent mode, no install ← priority ├── /shipped/ ★ what's on PyPI, honestly ← the navigation job ├── /cli/ 14 commands with real flags ├── /model/ nodes, edges, labels, layout — from code ├── /dsl/ the .issues flat-file DSL (undocumented today) ├── /concepts/ the foundational five ├── /roles/ the 11-role self-referential team ├── /examples/ the live 71-node graph, downloadable ├── /origins/ The Journey — voice memos to architecture ├── /network/ boundaries with graphs.sgit.ai and siblings ├── /documents/ raw markdown, source of truth ├── /admin/{comms,versions,index} · /about/participant.html └── /llms.txt + /llms-full.txt ``` --- ## `/` — the front page | Element | Content | Status | |---|---|---| | One line | *"A git-native issue tracker where the issues are files and the files are a graph."* | ✍️ | | The install | `pip install issues-fs-cli` — real, works today | ✅ | | **The package table** | 8 packages, 4 on PyPI, 2 of those empty. Above the fold | ✍️ from `04` §2 | | The three surfaces | lite markdown · `.issues` DSL · `--for-agent` JSON | ✍️ | | Proof strip | 71 nodes / 141 edges live · 604 tests · 14 commands · 4 backends | ✅ | | Honesty line | *"Two packages are real. Two are published but empty. Four aren't published. Here's the line."* | ✍️ | --- ## `/lite/` — the priority Full content ready in `02__issues-fs-lite.md`. Pages: | Page | Content | Status | |---|---|---| | `/lite/index.html` | Layout, task format, the four `mv` operations, the check-in cycle | ✍️ extract from `email-fs-lite-v0.6.md` §7 | | `/lite/five-minutes.html` | Worked example: three tasks, one blocked, one closed, actual commands. **Nothing in the corpus has this** | ✍️ fresh | | `/lite/vs-full.html` | The comparison table — `02` §4 | ✅ | | `/lite/team-view.html` | `find mail -path '*/issues/open/*.md'` and the own-queue-only rule | ✅ | **Feature two lines:** *"Be honest — if you don't know how to approach it yet, write that. Future you (or a different runtime) will read this."* and *"The protocol doesn't permit one agent to add tasks to another's queue directly — only by request. This is intentional: each agent owns their own work plan."* ⚠️ Carries a provenance note: the spec lives in `SGraph-AI__App__Send` (CC BY 4.0), not the Issues-FS repos (Apache 2.0). See `06` §4. --- ## `/shipped/` — the navigation job | Page | Content | Status | |---|---|---| | `/shipped/index.html` | The 8-package table with install commands and honest verdicts | ✍️ from `04` §2 | | `/shipped/why.html` | The `dev`→`main` release mechanism. **Answers every "why isn't it on PyPI" question in one table** | ✍️ from `04` §1 | | `/shipped/corrections.html` | S3, MGraph-DB, the lexicon, version and test counts — what the READMEs get wrong | ⚠️ from `07` | **The two empty wheels must be stated.** `issues_fs_service-0.2.0` ships 8 files and no FastAPI code while its summary promises *"FastAPI server with REST endpoints"*. Either fix upstream or say so — the house convention is to say so. --- ## `/start/` and `/cli/` Every command in `04` §4 verified against source. The quickstart works today: ```bash pip install issues-fs-cli issues-fs init issues-fs types init issues-fs create task "Write the /shipped page" --priority high --tags site,docs issues-fs link Task-1 blocks Bug-1 issues-fs list --for-agent ``` `/cli/` gets the full 14-command table with real flags, the three output formats, and the `-p` overload wart (`--path` on `init`, `--priority` on `create`/`update`). --- ## `/model/`, `/dsl/`, `/concepts/`, `/roles/`, `/examples/` | Page | Source | Status | |---|---|---| | `/model/` | `03__the-data-model.md` — schemas, the five regex primitives, the two-identity design, the double-stored edge | ✏️ | | `/model/layout.html` | The hierarchical `.issues/` tree; three incompatible layouts in circulation; **`_index.json` is a cache, not a source** | ⚠️ | | `/dsl/` | The `.issues` flat-file DSL — 11 source files, ~55 tests, 3 live examples, **zero documentation**. Parser tests are the spec until someone writes one | ✍️ fresh | | `/concepts/` | C1–C5 from `01__concepts-index.md` | ✅ | | `/concepts/lexicon.html` | ⚠️ Label clearly: ~7,000 words describing a package that was never built | ✏️ | | `/roles/` | 11 roles, each its own repo with its own `ROLE.md` and `.issues/`. *"The issue tracker tracks its own development"* | ✅ | | `/examples/` | The live 71-node graph as a download + the two config JSONs | ✅ | | `/origins/` | *The Journey* (3,483 w, Status: Historical Record) — voice memos → architecture. **And the fact that `thinking-in-graphs.md` (5 Feb 2026) is the origin of the estate's whole graph philosophy** | ✅ | | `/curiosities/` | The two screenplay parodies. Optional, cheap, memorable | ✅ | --- ## `/network/` — the boundary that matters **graphs.sgit.ai is the risk.** It was built from the Issues-FS concept documents and now teaches them at length. Duplicating them here makes two sites competing to be canonical. | Sibling | Boundary | |---|---| | **graphs.sgit.ai** | **They own the philosophy; this site owns the implementation.** Issues-FS is where the philosophy was *written* (Feb 2026) — say that, link there for the argument, and keep this site on *how it is built and how you use it*. The reciprocal link on graphs.sgit.ai is its open ask **N2** | | sgit.ai | Vaults and publishing. Issues-FS is git-native; sgit is vault-native. One paragraph on how they compose | | newsroom.sgit.ai | Shares the Librarian/Journalist/Historian role vocabulary | | pki.sgit.ai · nhi.sgit.ai | Minimal overlap. `person` is a node type; identity is theirs | --- ## Build order 1. ✍️ `/lite/` — the priority, homeless today, ~1,100 words ready 2. ✍️ `/shipped/` — the navigation job, nothing like it exists 3. ✅ `/start/` + `/cli/` — verified, works today 4. ✅ `/examples/` — the 71-node graph and the two config files 5. ✏️ `/model/` — from code, not prose 6. ✅ `/concepts/` — the foundational five 7. ✍️ `/dsl/` — the undocumented third surface 8. ✅ `/roles/` + `/origins/` 9. ⚠️ `/shipped/corrections.html` 10. ✏️ `/network/` — settle the graphs.sgit.ai boundary early --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).