# issues-fs.sgit.ai — the issues are files and the files are a graph > A node is a JSON file on disk. An edge is a typed verb stored on **both** endpoints. The > folder hierarchy is the containment structure. **Nothing runs** — no server, no daemon, no > database — so the tracker lives inside the repository it tracks, versions with it, branches > with it, and can be read by `cat`, `grep` and `find`. *Source: · site v0.1.1 · markdown twin of the front page.* --- ## What actually ships Queried live against PyPI on 22 August 2026; every wheel downloaded and unzipped. | PyPI package | Latest | Repo | Verdict | |---|---|---|---| | `issues-fs` | **0.7.0** | v0.7.1 | **Real** — 103-file wheel, 98 source files, 5,401 LOC, **604 tests** | | `issues-fs-cli` | **0.3.0** | v0.3.0 | **Real** — 23-file wheel, **14 commands**, 94 tests | | `issues-fs-service` | 0.2.0 | v0.2.0 | **Empty shell** — 8 files, no FastAPI code, while its summary promises a server | | `issues-fs-service-client-python` | 0.2.0 | v0.2.0 | **Empty shell** — 8 files, no client | | `issues-fs-service-ui` | — | v0.2.1 | Not published. 142 files in the repo | | `issues-fs-docs` | — | v0.1.6 | Not published. Its README shows a PyPI badge that 404s | | `issues-fs-dev` | — | v0.3.2 | Not published | | `issues-fs-dev-utils` | — | v0.1.1 | Not published. 535 LOC, absent from every ecosystem map | **Two packages are real. Two are published but empty. Four aren't published. Here's the line.** Why: CI publishes to PyPI only from `main`, and seven of eight repositories sit on `dev` ahead of `main`. `Issues-FS__Docs`'s `main` is still at *Initial commit*, 24 commits behind. [The whole mechanism](shipped/why.html) · [package by package](shipped/index.html). ## The part that 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 # same data, JSON, for an agent ``` [The walkthrough](start/index.html) · [all 14 commands](cli/index.html). ## Three agent-operable surfaces. One is documented. | | | | |---|---|---| | **1 · [Issues-FS-lite](lite/index.html)** | Markdown + YAML front-matter, three folders, four `mv` operations. No install, no runtime | Specification only | | **2 · [The `.issues` DSL](dsl/index.html)** | A line-oriented format parsed into nodes. 11 source files, ~55 tests, 3 live examples — and **zero prose documentation anywhere** until this site | Built and tested | | **3 · [`--for-agent` JSON](cli/index.html)** | Every one of the 14 commands forces JSON output | Shipping in 0.3.0 | No other project in the estate has three, and no document in the corpus says so. ## Numbers this site stands on **71** nodes and 141 link entries in the flagship live graph · **604** test functions across 45 files · **14** CLI commands, every one taking `--for-agent` · **4** storage backends · **147** nodes across the four live graphs · **1.5** lines of test per line of source. Measured, not quoted — [and the READMEs are wrong about the test count](shipped/corrections.html), twice, differently. ## Why a graph rather than a schema of fields A node has no inherent meaning; **meaning is discovered through the edges you can trace from it**. That is why the type system is a graph of typed relationships rather than a schema of fields, and why an edge type carries domain and range constraints. That thinking was written **here**. `thinking-in-graphs.md` is dated **5 February 2026**, was written for Issues-FS, and reached SGraph Send four months later. **The boundary:** [graphs.sgit.ai](https://graphs.sgit.ai) owns the philosophy and teaches it at length. **This site owns the implementation — and the origin.** [The full map](network/index.html). ## What this site says that the corpus does not - **Two published wheels are empty**, while their summaries describe code that is not in them. - **Four load-bearing README claims are false** — [all of them, with what was measured](shipped/corrections.html). - **`_index.json` is a cache, not a source.** One index says 22 issues where the disk has 24; the healthiest graph has none at all. [That is an argument, not an embarrassment](model/layout.html#index). - **The lexicon was never built** — ~7,000 words describing a package required by every repository. [Published as argued design](concepts/lexicon.html). ## For an agent Issues-FS is a git-native tracker with three operable surfaces. With a filesystem and no tooling, use **lite**: `issues/open|blocked|done/NNN-slug.md` with YAML front-matter, and four `mv` operations. With `issues-fs` on the path, pass `--for-agent` to any of the 14 commands to force JSON. Read another agent's `issues/`; never write into it. Do not rely on `_index.json` — walk the tree. Four claims in the upstream READMEs are false; check [/shipped/corrections.html](shipped/corrections.html) before repeating any of them. --- Published by the sgit project, which builds and uses Issues-FS — [participant disclosure](about/participant.html). Site content CC BY 4.0; the upstream Issues-FS repositories are Apache 2.0 and name no copyright holder.