# 06 — Boundaries, Corrections and House Style --- ## 1. The graphs.sgit.ai boundary — settle this first `thinking-in-graphs.md`, `compatibility-through-connectivity.md` and `lexicon-architecture.md` were written **for Issues-FS on 5 February 2026**. They were imported into SGraph Send on 11 June and are now the foundation of graphs.sgit.ai and its book. Two sites now have a claim on the same five documents. Resolve it explicitly: > **graphs.sgit.ai owns the philosophy. issues-fs.sgit.ai owns the implementation — and the origin.** Practically: - `/concepts/` here gives each idea **one screen and a link**, not a chapter - `/origins/` states plainly that this is where the thinking was written, with dates - Everything unique to Issues-FS — the schemas, the CLI, lite mode, the DSL, the roles, the live graphs — is **only here** - graphs.sgit.ai's open ask **N2** is a reciprocal `/graphs/` bridge page. Offer the `/issues-fs/` half in exchange ⚠️ The graphs.sgit.ai book review **r001 item 8** explicitly requests *"IssuesFS ontologies & repo"* as a case study. This pack is that answer — coordinate so the two sites tell one story rather than two. --- ## 2. Corrections required before republication Four load-bearing claims appear in multiple READMEs and are false. **Do not carry them onto the site.** | Claim | Where | Measured reality | |---|---|---| | **S3 storage backend** | `Issues-FS/README.md`, `Issues-FS__Dev/README.md`, `.claude/CLAUDE.md`, architecture overview | `Enum__Graph__Storage__Backend` = MEMORY / LOCAL_DISK / SQLITE / ZIP. memory-fs 0.41.0 ships no S3 provider. Only the memory-fs abstraction doc gets it right | | **MGraph-DB integration** | `Issues-FS/README.md`, `.claude/CLAUDE.md` tech stack, architecture overview | **`mgraph-db` in zero `pyproject.toml`; `import mgraph_db` in zero source files.** `issues_fs/mgraph/` is a hand-rolled ~220-LOC in-memory graph borrowing the four-layer *naming convention* only | | **`issues-fs-lexicon`** — *"required by every Issues-FS repository"*, the "two-dependency invariant" | lexicon-architecture v1 + v2, ~7,000 w | No repo, no PyPI package, in no `pyproject.toml` | | **Version and tests** | `Issues-FS/README.md`: "v0.4.5", "475+ tests / 36 files" | Repo v0.7.1, PyPI 0.7.0, **604 tests / 45 files**. `Issues-FS__Dev/README.md` says "552+" — a third number | More, from the same audit: | Claim | Reality | |---|---| | `pip install issues-fs-docs` + PyPI badge | **404** | | `pip install issues-fs-dev-utils` | **404** | | `issues-fs-service` summary: *"FastAPI server with REST endpoints"* | 8-file wheel, no FastAPI code | | `issues-fs-service-client-python` summary: *"API schemas and Python client"* | 8-file wheel, no client | | *"17 git submodules"* (twice in `CLAUDE.md`) | **19 gitlinks** | | *"a team of 10 specialized AI agent roles"* | **11 role repos** — Designer is undocumented | | `Client__JS`, `Service__GitHub`, `Service__S3`, `Service__Jira` | No repos, no npm package | | `issues-fs-github-backup` — *"installable via PyPI, 3-command path to value"* | Does not exist | | `MGraph__Issues__Sync__Service` with example code in the README | Only at `to_refactor-in/…`, unpackaged and unimportable | | `Graph__Repository__Factory(root_path=…).create_repository()` in the README | No such `__init__`, no such method — classmethods only | | `**Date:** YYYY-MM-DD` | Unfilled template placeholder in a committed doc | **The house move is not to hide these.** pki.sgit.ai shipped a page listing *"five things earlier briefs got wrong"* and it is one of the strongest pages on that site. Do the same at `/shipped/corrections.html`. --- ## 3. Built but undocumented — the site's opportunity | Built | Documentation today | |---|---| | **The `.issues` flat-file DSL** — 11 source files, ~55 tests, 3 live examples, wired into the repository API | **Zero prose anywhere.** The newest, most distinctive feature, invisible | | **Status services** — 5 services + 6 schemas producing a full health payload (git branch/commit/dirty, backend + writability + file count, type counts, index stats) | Mentioned nowhere outside code | | `Comments__Service` — 234 LOC, full CRUD | CLI lists the commands; no design doc | | Phase-1 root selection and hierarchical children — 3 services, 2 schema modules, a REST surface, UI services | Only in dev-briefs marked "Ready for Implementation" | | `Issues-FS__Dev__Utils` — 535 LOC, 19 tests, a 14-topic Librarian-maintained `topic_map.json` | Good user guide; **absent from every ecosystem map** | | The **Designer** role (11th submodule) | Named in no README, no role table, no role document | | The `automation-runner` UI app (803 LOC of scripted scenarios) | Not in the IFD docs set | **Each of these is a page nobody else can write.** The DSL in particular deserves `/dsl/`. --- ## 4. Licence — three things to resolve before launch All nine repos ship byte-identical **Apache 2.0** (`md5 86d3f3a95c324c9479bd8986968f4327`). **4.1 No copyright holder is named anywhere.** Every `LICENSE` ends with the unfilled appendix placeholder `Copyright [yyyy] [name of copyright owner]`. No repo has a `NOTICE` file. Author metadata exists only in `pyproject.toml` (`Dinis Cruz `) and PyPI. **Apache 2.0 §4(c)/(d) attribution is unanchored.** Fix at source. **4.2 The CC BY 4.0 claim has no backing.** `Issues-FS__Dev/README.md` states *"Documentation and knowledge content are published under CC BY 4.0."* That sentence is the **only** occurrence of "CC BY" or "Creative Commons" in the entire corpus. `Issues-FS__Docs` — which holds all 59 documents — ships Apache 2.0 and says nothing about it. **No document carries a per-document licence line.** Given the 21 August CC BY 4.0 decision for the `*.sgit.ai` estate, either add a `LICENSE-docs` to `Issues-FS__Docs` making the dual licence real, or publish the documents under Apache 2.0 and note the difference. **Do not assume CC BY on the strength of one README sentence.** The `licence-audit.py` script from the graphs pack runs here unchanged. **4.3 Imported third-party content is unattributed.** The MGraph-DB briefing (5,375 w) and seven type-safety briefs (~24,000 w) are about sibling `owasp-sbot` projects — almost certainly compatibly licensed, but carrying no source attribution or licence line. **~29,000 words, roughly 18% of the corpus.** **Cross-boundary note:** Issues-FS-lite comes from `SGraph-AI__App__Send` (CC BY 4.0), not the Issues-FS repos (Apache 2.0). State the source licence on `/lite/`, per the provenance contract in the newsroom pack. **Third-party runtime deps for a licence page:** `osbot-utils` 3.75.0, `memory-fs` 0.41.0, `osbot-fast-api`, `osbot-fast-api-serverless` 1.34.0 (all `owasp-sbot`, Apache 2.0); `typer`, `fastapi`/`starlette` (MIT/BSD). The UI loads d3, mermaid, vis-network, cytoscape, cytoscape-dagre and dagre from public CDNs — **none vendored, none attributed.** --- ## 5. House style, inherited Full treatment in the graphs pack `06__house-style-and-conventions.md`. Essentials: - `/llms.txt` at root, **treated as the whole surface** — each entry carries the page's single most important fact, not just its topic. Plus `/llms-full.txt` as a single-file concatenation. Measured on sgit.ai: the index fetch worked, then link-following failed because agent fetch tools refuse URLs a search has not returned - `/documents/` with raw markdown as source of truth, rendered pages as presentation - `/admin/comms.html` with numbered asks (N1, N2…) and tasks (T1, T2…) in explicit states. **Seed it with:** N1 the copyright holder, N2 the CC BY decision, N3 the two empty wheels, N4 merging `Issues-FS__Docs` dev→main, N5 the reciprocal graphs.sgit.ai bridge - `/admin/versions.html`, `/about/participant.html`, a build order published unresolved with open questions and honest tensions - **Voice:** short declarative sentences making checkable claims; publish the argument before the implementation and say which is which; name what you got wrong; no marketing adjectives - **Every section serves three readers:** documentation · live demonstration · **agent guidance**. For this site the third is the product — Issues-FS has three agent-operable surfaces. End every page with a pasteable "for an agent" block --- ## 6. Two demonstrations to build in 1. **Track this site's own build in Issues-FS.** Publish `.issues/` in the site repo and render it at `/examples/this-site/`. The ecosystem already claims *"the issue tracker tracks its own development"* — make it visible. Costs one `issues-fs init`. 2. **Ship the two config JSONs as downloads.** 12 node types, 10 verb pairs with domain/range constraints, plus the 71-node graph. Cheapest credibility available, and it answers graphs.sgit.ai's open task **T2** at the same time. --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).