# 01 — Concepts Index The conceptual layer. **Issues-FS is where the graph philosophy of the whole estate was written** — `thinking-in-graphs.md` is dated **5 February 2026** and did not reach SGraph Send until 11 June. graphs.sgit.ai is built on it. This site is its origin, and should say so. All paths relative to `Issues-FS__Docs`. Word counts measured. --- ## The foundational five ### C1 · Thinking in Graphs — **the entry point** A node has no inherent meaning; meaning is *discovered* through the edges you can trace from it, and confidence is proportional to how richly the node connects to others that supply context. The document insists this is literal architecture, not metaphor: it is why Issues-FS stores nodes-plus-edges, how it validates assumptions, how it handles ambiguity, and how it coordinates work across boundaries of language, culture, ownership and intent. `docs/to_classify/v0_4_0__issues-fs__thinking-in-graphs.md` · **5,013 w** · v1.0, 2026-02-05, "Scope: Foundational" · **Newcomer-ready: YES — the single best entry point.** Self-declares as the root of the doc graph. ### C2 · Compatibility Through Connectivity Architecture docs, diagrams, ADRs, code, tests, OpenAPI specs, Terraform, runbooks and runtime traces are different *languages* describing what should be the *same truth*. Extract a graph from each and compatibility becomes measurable: not *"does the code work?"* but ***"do all representations of this system agree on what it is?"*** `docs/to_classify/6-feb-other/v0_4_0__issues-fs__compatibility-through-connectivity.md` · **3,847 w** · Status: **Foundational** · **YES** — opens with a clear nine-artefact table and a one-line thesis. ### C3 · LLM as Execution Engine — **most quotable** When you specify `extract_semantic_graph(text, ontology)` you do not have to implement it — an LLM can *act as* that function: same inputs, same logic, same outputs, and callers cannot tell. This lets you run the architecture today, validate a design before writing it, discover edge cases cheaply, and swap in real code as patterns solidify. **The prompt is the specification; the LLM is the implementation.** `docs/to_classify/6-feb-other/v0_4_0__issues-fs__llm-as-execution-engine.md` · **3,884 w** · Status: Practical Guide · **YES** ### C4 · Lexicon Architecture (v2) `Issues-FS__Lexicon` is defined not as a schema registry nor an authority on definitions, but as *the most well-connected graph in the ecosystem* — anchor nodes any scope may link to in order to raise the confidence and interoperability of its own nodes. Establishes the **two-dependency invariant**: every repo depends on `osbot-utils` (how we build) and `issues-fs-lexicon` (what we can link to). `docs/to_classify/v0_4_0__issues-fs__lexicon-architecture-v2.md` · **4,485 w** · v2.0, 2026-02-05 · Mostly newcomer-ready; names C1 as prerequisite. ⚠️ **`issues-fs-lexicon` does not exist** — no repo, no PyPI package, in no `pyproject.toml`. ~7,000 words across two versions describing a package that was never built. Publish as **argued design**, clearly labelled. 🚫 The v1 at `docs/to_classify/already-legacy/v0.1.0__issues-fs__lexicon-architecture.md` (2,509 w) sits in a folder called `already-legacy` but carries **no Superseded marker in the file**. Do not publish; add the marker at source. ### C5 · Use-Case Pattern Answers the adoption gap. A platform answer (*"you can create graphs of issues with typed relationships and…"*) is a read-the-docs answer, not a ten-minute answer. Use cases are pre-packaged answers to one problem each, named `Issues-FS__Use_Case__` / `issues-fs-`, installable and valuable within minutes. `docs/to_classify/6-feb/v0_4_0__issues-fs__use-case-pattern.md` · **2,909 w** · **YES** Worked example: `docs/to_classify/6-feb/v0_4_0__issues-fs__use-case__github-backup.md` (2,549 w) ⚠️ describes `issues-fs-github-backup`, *"installable via PyPI, 3-command path to value"* — **which does not exist.** --- ## The testing and semantics thread | Concept | Path | Words | Note | |---|---|---|---| | **Semantic testing DSL** | `docs/to_classify/6-feb/v0_4_0__issues-fs__semantic-testing-dsl.md` | 3,461 | `for each Risk in document / assert Risk.remediation exists`. Explicitly against Gherkin — *"English pretending to be code, with a brittle translation layer"*. Compiles to typed Python/JS running against graph structure, so rewording a paragraph does not break a test. **Self-flags `[NEEDS EXPLORATION]`** — needs framing | | **Semantic text architecture** | `docs/to_classify/6-feb/v0_4_0__issues-fs__semantic-text-architecture.md` | 2,996 | "Text as graph" — prerequisite for the DSL | | **Semantic graph code representation** | `docs/to_classify/6-feb/v0_4_0__issues-fs__semantic-graph-code-representation.md` | 2,868 | Graph→code compilation; why tests target code, not text | | **Architecture testing worked example** | `docs/to_classify/6-feb-other/v0_4_0__issues-fs__architecture-testing-worked-example.md` | 4,495 | Food-delivery worked example. Status: Practical Guide | --- ## The role ecosystem Ten named roles, six conventional (Dev, QA, Architect, DevOps, AppSec, Conductor) and four unconventional (**Librarian, Cartographer, Historian, Journalist**). The argument is that the unconventional four are architecturally *central*, not secondary: in a system where meaning comes from connectivity, **the Librarian is the meaning-making role**; the Cartographer adds position to connectivity via Wardley Maps; the Journalist captures the present with enough fidelity that the Historian has pivot points to find. | Document | Path | Words | Note | |---|---|---|---| | **Roles — practical** | `docs/development/guide__agentic-role-based-workflow.md` | **5,814** | Status **Active**. **The most operationally useful doc in the corpus** — has a Quick Start checklist and a `ROLE.md` template | | Roles — overview | `docs/to_classify/9-feb/v0_4_0__issues-fs__role-ecosystem-guide.md` | 4,475 | v2.0, 2026-02-09 · **YES** | | Roles — architecture | `docs/to_classify/v0.1.0__issues-fs__role-based-agent-coordination.md` | 3,970 | ⚠️ says *"The initial roles are: Dev, QA, DevOps, Architect, Librarian, and Conductor"* — six, then ten, then eleven, **with no supersession note** | | Roles — stress test | `docs/to_classify/v0.1.0__issues-fs__role-architecture-framework-analysis.md` | 3,743 | Tests roles against Wardley Maps + four other frameworks | | Individual roles | `docs/to_classify/6-feb/…librarian-role.md`, `9-feb/…historian-role.md`, `9-feb/…journalist-role.md`, `07-feb/…cartographer-role.md` | ~4,500 each | The four unconventional roles, one document each | **The self-referential claim, worth featuring:** each role is a **separate GitHub repository**, added as a submodule to `Issues-FS__Dev` on branch `dev`, each with its own `ROLE.md` and its own `.issues/` directory. From `Issues-FS__Dev/README.md`: *"The agents collaborate through Issues-FS itself… This creates a self-referential system: **the issue tracker tracks its own development**."* ⚠️ **19 gitlinks measured**, not the 17 claimed twice in `.claude/CLAUDE.md`, and **11 role repos**, not the 10 claimed. The **Designer** role is the 11th submodule and is named in no README, no role table and no role document. --- ## Architecture and integration | Document | Path | Words | Verdict | |---|---|---|---| | **Memory-FS abstraction** | `docs/issues_fs/architecture/0.41.0__issues-fs__memory-fs-abstraction-layer.md` | 901 | ✅ **Short, accurate, matches code.** The only doc that gets the backend list right | | Ecosystem architecture | `docs/issues_fs/architecture/v0.4.0__issues-fs__architecture-overview.md` | 1,050 | ⚠️ Status "Active" but **stale** — lists four service repos that do not exist (`Client__JS`, `GitHub`, `S3`, `Jira`) | | MGraph-DB briefing | `docs/library/mgraph-db/v1_10_6__mGraph-db__llm_briefing.md` | 5,375 | ⚠️ An **imported briefing about MGraph-DB itself**, not about Issues-FS's use of it. **No document describes an actual integration — because there isn't one** (see `07__gaps`) | | Graph-based issue tracking | `docs/issues_fs/llm-briefs/v0.2.14__briefing__graph-based-issue-tracking.md` | — | The storage-backend decision tree, in ASCII | --- ## Historical and unexpected | Document | Path | Words | Note | |---|---|---|---| | **The Journey** | `docs/to_classify/6-feb-other/v0_4_0__issues-fs__the-journey.md` | 3,483 | Status: **Historical Record** — voice memos → architecture. The `/origins/` page, pre-written | | Screenplay: *Graphs of Glory* | `docs/to_classify/6-feb-other/funny-stories/graphs-of-glory-screenplay.md` | 3,768 | A parody screenplay about graphs | | Screenplay: *The Graph Awakens* | `docs/to_classify/6-feb-other/funny-stories/the-graph-awakens-screenplay.md` | 2,837 | Ditto | Two screenplay parodies sit in a technical documentation repo. They are genuinely unusual, they are CC-publishable, and no sibling site has anything like them. **Consider a `/curiosities/` page** — it costs nothing and it is the kind of thing people remember. --- ## Type-safety briefs — 7 documents, ~24,000 words `docs/development/llm-briefs/type-safety/` — `Type_Safe`, safe primitives, collections subclassing, decorators, testing guidance, no-raw-primitives policy, plus a Python formatting guide. These are **imported briefings about `osbot-utils`**, a sibling `owasp-sbot` project. They carry **no source attribution and no licence line**. Together with the MGraph-DB briefing that is ~29,000 words, roughly **18% of the corpus**, of third-party-derived content. See `06__boundaries-and-house-style.md` §4. --- ## Teaching order for the site | # | Page | Source | Status | |---|---|---|---| | 1 | **What Issues-FS is in one screen** | — | ✍️ fresh | | 2 | **Thinking in graphs** | C1 | ✅ | | 3 | **Nodes, edges and labels** — from code | `03__the-data-model.md` | ✏️ | | 4 | **Issues-FS-lite** — the no-install path | `02__issues-fs-lite.md` | ✍️ extract | | 5 | **Five minutes with the CLI** | `04__what-ships.md` §4 | ✅ | | 6 | **Compatibility through connectivity** | C2 | ✅ | | 7 | **LLM as execution engine** | C3 | ✅ | | 8 | **The lexicon** — argued, not built | C4 | ✏️ label clearly | | 9 | **Use cases** | C5 | ✏️ drop the non-existent example | | 10 | **The roles** | role docs | ✅ | | 11 | **Semantic testing** | DSL thread | ✏️ mark exploratory | | 12 | **The journey** | Historical Record | ✅ | --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).