The foundational five
Five documents, written for Issues-FS in February 2026, that became the conceptual foundation of the whole *.sgit.ai estate. Each gets one screen here and a link out for the argument. That is deliberate: graphs.sgit.ai teaches this material at length and owns it. This site is where it was written, and its job is to show what it produced in code.
The boundary, so nobody has to guess. Two sites have a claim on these documents. The resolution is: graphs.sgit.ai owns the philosophy; issues-fs.sgit.ai owns the implementation — and the origin. Duplicating the argument here would make two sites compete to be canonical on the same five documents, which serves nobody. The full boundary map.
C1 · Thinking in graphs
5,013 words · v1.0, 5 February 2026 · Scope: Foundational · the single best entry point in the corpus, and its self-declared root
A node has no inherent meaning. Meaning is discovered through the edges you can trace from it — and confidence in that meaning is proportional to how richly the node connects to others that supply context.
The document insists this is literal architecture rather than metaphor, and Issues-FS is the proof: it is why the tracker stores nodes-plus-edges rather than records-with-fields, why an edge type carries domain and range constraints, and why ambiguity is handled by adding connections rather than by adding fields.
This is the origin document of the estate's graph thinking. It was written for Issues-FS on 5 February 2026 and reached SGraph Send on 11 June — four months later. The dates, and why they matter.
The argument at length, on graphs.sgit.ai →
C2 · Compatibility through connectivity
3,847 words · Status: Foundational · opens with a nine-artefact table and a one-line thesis
Architecture documents, diagrams, ADRs, code, tests, OpenAPI specs, Terraform, runbooks and runtime traces are different languages describing what is supposed to be the same truth. Extract a graph from each and compatibility stops being a matter of opinion:
The question is not “does the code work?” It is “do all representations of this system agree on what it is?”
Issues-FS is one such representation — the one that holds intent. A tracker living inside the repository it tracks is the cheapest possible instance of the argument: the issue and the code it refers to are in the same commit, so they can be checked against each other.
The argument at length, on graphs.sgit.ai →
C3 · LLM as execution engine
3,884 words · Status: Practical Guide · the most quotable idea in the corpus
The prompt is the specification; the LLM is the implementation.
When you specify a function like extract_semantic_graph(text, ontology), you do not have to implement it. An LLM can act as that function — same inputs, same contract, same outputs — and callers cannot tell the difference. So you can run the architecture today, validate a design before writing it, discover edge cases cheaply, and swap in real code as the patterns solidify.
This is the idea that makes Issues-FS-lite coherent rather than a compromise. Lite has no implementation and needs none: the protocol is four operations described precisely enough that an agent executes them directly. The specification is the implementation, and the runtime is whatever is reading it.
C4 · Lexicon architecture
4,485 words (v2) · 5 February 2026 · never built
Defines issues-fs-lexicon not as a schema registry and not as an authority on definitions, but as the most well-connected graph in the ecosystem — a set of anchor nodes that any scope may link to in order to raise the confidence and interoperability of its own nodes.
It is the most-theorised and least-built idea in the corpus: roughly 7,000 words across two versions, describing a package with no repository, no PyPI entry, and no appearance in any pyproject.toml. It is published here as argued design, clearly labelled — on its own page, with what it claimed and what exists.
C5 · The use-case pattern
2,909 words · newcomer-ready
Answers the adoption gap directly. A platform answer — “you can create graphs of issues with typed relationships and…” — is a read-the-documentation answer, not a ten-minute answer. Use cases are pre-packaged answers to one problem each, named Issues-FS__Use_Case__<Name> / issues-fs-<name>, installable and valuable within minutes.
The pattern is sound and this site takes it seriously — the quickstart and the lite walkthrough are both attempts at the ten-minute answer. The worked example in the corpus is not usable as written: it describes issues-fs-github-backup as “installable via PyPI, 3-command path to value”, and that package does not exist.
The other nine
Beyond the foundational five, the corpus carries a testing-and-semantics thread and a set of role documents. Summarised rather than reproduced:
| Document | Words | Note |
|---|---|---|
| Semantic testing DSL | 3,461 | for each Risk in document / assert Risk.remediation exists. Explicitly against Gherkin — “English pretending to be code, with a brittle translation layer” — and compiles to typed code running against graph structure, so rewording a paragraph does not break a test. self-flags NEEDS EXPLORATION |
| Semantic text architecture | 2,996 | “Text as graph” — the prerequisite for the DSL above |
| Semantic graph code representation | 2,868 | Graph→code compilation; why tests should target code rather than text |
| Architecture testing worked example | 4,495 | A food-delivery worked example. Status: Practical Guide |
| Agentic role-based workflow | 5,814 | Status Active. The most operationally useful document in the corpus — a Quick Start checklist and a ROLE.md template. The roles |
| Role ecosystem guide | 4,475 | v2.0, 9 February 2026 — ten roles, six conventional and four not |
| Role-based agent coordination | 3,970 | ⚠️ Says the initial roles are six. There are now eleven. No supersession note in the file |
| Role architecture framework analysis | 3,743 | Stress-tests the roles against Wardley Maps and four other frameworks |
| Memory-FS abstraction layer | 901 | ✅ Short, accurate, matches the code. The only document that gets the backend list right — the four real backends |
What is cited and not republished
Roughly 29,000 words — about 18% of the corpus — are imported briefings about sibling projects: one about a graph database library (5,375 words) and seven about the type-safety utilities Issues-FS builds on (~24,000 words). They carry no source attribution and no licence line. They are almost certainly compatibly licensed, and this site still does not republish them: material whose provenance is unrecorded is exactly the material a site about honest documentation should not pass along without saying so. Resolving it upstream is open request N2.
Two further documents are not published: a superseded v1 of the lexicon architecture that sits in a folder named already-legacy/ while carrying no supersession marker in the file itself, and a staging directory of un-migrated code. Both are recorded on the documents page with the reason.
For an agent
Five foundational documents, written for Issues-FS in February 2026: thinking in graphs (a node has no inherent meaning; meaning comes from traceable edges — the origin document, 5 Feb 2026), compatibility through connectivity (do all representations of this system agree on what it is), LLM as execution engine (the prompt is the specification, the LLM is the implementation), the lexicon (argued, never built — do not treat as a dependency), and the use-case pattern. For the philosophy in depth go to graphs.sgit.ai; for how it is implemented, stay here. Do not cite the imported third-party briefings from this corpus — their provenance is unrecorded.