# 04 — What Ships: the navigation deliverable

**The commissioning brief asks the site to "provide a nice way to navigate what already exists and has shipped (like what is on PyPI)." This file is the evidence for that.**

Everything measured against local clones and **live PyPI queries**. Nothing estimated.

---

## 1. The release mechanism — read this first

Every repo carries three workflows: `ci-pipeline.yml` (reusable base), `ci-pipeline__dev.yml`, `ci-pipeline__main.yml`.

- Push to **`dev`** → run `tests/unit`, increment **minor** tag, `should_publish_pypi: **false**`
- Push to **`main`** → run `tests/unit`, increment **major** tag, `should_publish_pypi: **true**`

**Consequence: PyPI only ever receives what has been merged to `main`.** Seven of eight repos sit on `dev`, ahead of `main`:

| Repo | dev ahead of main | `main` HEAD |
|---|---|---|
| **Issues-FS__Docs** | **24** | `4a06feb Initial commit` (2026-02-05) |
| Issues-FS__CLI | 8 | `b32bb7b` (2026-02-10) |
| Issues-FS__Service | 5 | `cc6e6b9` (2026-02-05) |
| Issues-FS__Dev__Utils | 5 | `e88be0a Initial commit` (2026-02-11) |
| Issues-FS__Dev | 3 | `b9ca982` (2026-02-18) |
| Issues-FS__Service__Client__Python | 3 | `db60e7c` (2026-02-05) |
| Issues-FS | 1 | `a428b79` (2026-02-15) |
| Issues-FS__Service__UI | 1 | `35c80c6` (2026-02-10) |

Release helper, identical in every repo: `scripts/gh-release-to-main.sh` — `git merge --no-ff dev` into `main`, push, merge back.

**This single table explains every "why isn't it on PyPI" question the site will get.** Publish it.

---

## 2. The package table

Queried `https://pypi.org/pypi/<name>/json` live, wheels downloaded and unzipped.

| PyPI name | On PyPI | Latest | Releases | First → last upload | Repo version | Verdict |
|---|---|---|---|---|---|---|
| `issues-fs` | ✅ | **0.7.0** | 5 | 2026-02-04 → 2026-02-15 | v0.7.1 | **Real** — 103-file wheel |
| `issues-fs-cli` | ✅ | **0.3.0** | 2 | 2026-02-06 → 2026-02-10 | v0.3.0 | **Real** — 23-file wheel |
| `issues-fs-service` | ✅ | 0.2.0 | 1 | 2026-02-05 | v0.2.0 | ⚠️ **8-file wheel. No FastAPI code** |
| `issues-fs-service-client-python` | ✅ | 0.2.0 | 1 | 2026-02-05 | v0.2.0 | ⚠️ **8-file wheel. No client** |
| `issues-fs-service-ui` | ❌ 404 | — | 0 | — | v0.2.1 | 142 files in repo |
| `issues-fs-docs` | ❌ 404 | — | 0 | — | v0.1.6 | README shows a 404 badge |
| `issues-fs-dev` | ❌ 404 | — | 0 | — | v0.3.2 | — |
| `issues-fs-dev-utils` | ❌ 404 | — | 0 | — | v0.1.1 | 535 LOC, 19 tests |

**The two empty wheels are the sharpest honesty item on the site.** `issues_fs_service-0.2.0` contains `__init__.py`, `utils/Version.py`, `utils/__init__.py`, `version` and dist-info — that is all — while its PyPI summary reads *"FastAPI server with REST endpoints"*. Same shape for the client. Either yank/republish them or say so on the page. Following house convention: **say so.**

---

## 3. `issues-fs` — the core library ✅

- **Install:** `pip install issues-fs`
- **Repo:** 197 tracked files, 66 commits, 2026-02-04 → 2026-02-18
- **Source:** 98 `.py`, **5,401 LOC** · **Tests: 604 functions / 45 files / 8,213 test LOC** — 1.5 test LOC per source LOC
- **Deps:** `python ^3.12`, `osbot-utils`, `memory_fs`, `issues-fs-cli` ← ⚠️ **circular: the core library depends on its own CLI**
- **No CLI and no HTTP in this package** — it is an importable Python API

**Public surface** (cite these on `/api/`):

| Class | Path | Key methods |
|---|---|---|
| `Graph__Repository` | `issues_fs/issues/graph_services/Graph__Repository.py` (496 L) | `node_save/load/load_by_path/load_by_label/delete/exists`, `nodes_list_all`, `type_index_*`, `global_index_*`, `node_types_*`, `link_types_*`, `attachment_*`, `issues_files_*`, `clear_storage` |
| `Graph__Repository__Factory` | `.../Graph__Repository__Factory.py` | `create_memory()`, `create_local_disk(root_path)`, `create_sqlite(db_path)`, `create_zip(zip_path)`, `create(backend, …)` |
| `Node__Service` | `.../Node__Service.py` (472 L) | `create/get/update/delete_node`, `get_node_graph`, **`traverse_graph`**, **`find_incoming_links`**, `parse_label_to_type` |
| `Link__Service` | `.../Link__Service.py` (227 L) | `list_links`, `create_link`, `delete_link`, `find_link_type` |
| `Type__Service` | `.../Type__Service.py` (286 L) | node-type and link-type CRUD, `initialize_default_types` |
| `Comments__Service` | `.../Comments__Service.py` (234 L) | full comment CRUD |
| Status services | `issues_fs/issues/status/` | `Storage__`, `Git__`, `Types__`, `Index__`, `Server__Status__Service` |
| `.issues` DSL | `issues_fs/issues/issues_file/` | parser, loader, check, normalise, schema, node factory |
| In-memory graph | `issues_fs/mgraph/MGraph__Issues__Domain.py` (163 L) | `add_node/add_edge/get_node_by_*/get_children/get_ancestors/node_count/edge_count` |

⚠️ `to_refactor-in/` (12 files) is a staging area of un-migrated code still importing `mgraph_ai_ui_html_transformation_workbench` — the project Issues-FS was extracted from.

---

## 4. `issues-fs-cli` — the end-user surface ✅

- **Install:** `pip install issues-fs-cli` → console script **`issues-fs`**
- **Framework:** Typer · `help="Git-native graph-based issue tracking"` · `no_args_is_help=True`
- **Source:** 17 `.py`, 1,080 LOC · **Tests: 94 functions / 7 files**
- **Repo discovery:** `CLI__Context.discover_issues_root()` walks up from cwd looking for `.issues/` — git-style

**All 14 commands, verified against source:**

| Command | Positional | Options |
|---|---|---|
| `issues-fs init` | — | `--path/-p` (default `.`), `--for-agent` |
| `issues-fs create <node_type> <title>` | node_type, title | `--description/-d`, `--status/-s`, `--priority/-p`, `--tags/-t`, `--output/-o`, `--for-agent` |
| `issues-fs show <label>` | label | `--depth/-D` (default 0), `--output/-o`, `--for-agent` |
| `issues-fs list` | — | `--type/-t`, `--status/-s`, `--output/-o`, `--for-agent` |
| `issues-fs update <label>` | label | `--title/-T`, `--description/-d`, `--status/-s`, `--priority/-p`, `--tags/-t`, `--output/-o`, `--for-agent` |
| `issues-fs delete <label>` | label | `--force/-f`, `--output/-o`, `--for-agent` |
| `issues-fs link <source> <verb> <target>` | 3 | `--output/-o`, `--for-agent` |
| `issues-fs unlink <source> <target>` | 2 | `--output/-o`, `--for-agent` |
| `issues-fs links <label>` | label | `--output/-o`, `--for-agent` |
| `issues-fs comment <label> <text>` | label, text | `--author/-a` (default `cli-user`), `--output/-o`, `--for-agent` |
| `issues-fs comments <label>` | label | `--output/-o`, `--for-agent` |
| `issues-fs types list` | — | `--output/-o`, `--for-agent` |
| `issues-fs types init` | — | `--for-agent` |
| `issues-fs link-types list` | — | `--output/-o`, `--for-agent` |

**Output formats** (`CLI__Output.py`): `table` (default), `json`, `markdown`. **`--for-agent` forces JSON.**

⚠️ Known wart worth documenting rather than hiding: **`-p` is overloaded** — `--path` on `init`, `--priority` on `create` and `update`.

**The five-minute quickstart the site needs** — every command verified to exist:

```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 create bug "PyPI badge 404s in Docs README"
issues-fs link Task-1 blocks Bug-1
issues-fs list --output table
issues-fs show Task-1 --depth 1
issues-fs list --for-agent          # same data, JSON, for an agent
```

---

## 5. The three agent-operable surfaces

**This is the site's most distinctive claim and no current document makes it.**

| Surface | What it is | Status |
|---|---|---|
| **1 · Issues-FS-lite** | Markdown + YAML front-matter, three folders, four `mv` ops. **No install, no runtime** | Specification only — and it lives in another repo. See `02__issues-fs-lite.md` |
| **2 · The `.issues` flat-file DSL** | Line-oriented text parsed into nodes. 11 source files, ~55 tests, 3 live examples, wired into `Graph__Repository.issues_files_*` | **Built and tested. Zero prose documentation anywhere** |
| **3 · `--for-agent` JSON** | Every one of the 14 CLI commands forces JSON output | Shipping in `issues-fs-cli` 0.3.0 |

Surface 2 is the find. `Issues-FS`'s own `.issues/` folder contains three live `.issues` files — `bugs-parser.issues`, `workstream-integration.issues`, `workstream-issues-file-parser.issues`. **The parser tests and those three files are the only specification that exists.**

---

## 6. `issues-fs-service` / `-client-python` ⚠️ published but empty

Six commits each, all 2026-02-05, and nothing since. Both wheels contain 8 files and no functional code. `issues-fs-service` declares `osbot-fast-api` as a dependency but ships no FastAPI application.

**No HTTP endpoint exists in any published package.** If the site documents an API surface, it must be marked as design.

---

## 7. `issues-fs-service-ui` — unpublished, but the largest UI artefact

- 142 files, 27 commits, **v0.2.1 in repo, not on PyPI**
- Includes an `automation-runner` app (803 LOC of scripted scenarios) that appears in no documentation
- Loads d3, mermaid, vis-network, cytoscape, cytoscape-dagre and dagre from public CDNs — none vendored, none licence-attributed
- Tests: 2 files, 3 functions, **plus a fully commented-out Playwright suite**
- Carries its own live `.issues/` graph: **49 nodes, 22 link entries**, 9 node types

Run locally via `scripts/run-locally.sh`. ⚠️ That script's comment says "default port 10041" above `PORT=${…:-10051}`.

---

## 8. `issues-fs-dev-utils` — the orphan

535 LOC, 19 tests, a good `docs/user-guide.md`, and a 14-topic Librarian-maintained `topic_map.json`. **Absent from every ecosystem map** — not in `Issues-FS__Dev`'s repo table, not in `Issues-FS`'s, not in the architecture overview. Cross-repo developer productivity tooling that nobody can find.

---

## 9. The live graphs — real, downloadable examples

| Repo | Nodes | Link entries | Node types | Layout | `.issues` DSL files |
|---|---|---|---|---|---|
| **`SGraph-AI__App__Send`** | **71** | **141** | task 54, feature 9, phase 5, project 1, git-repo 1, bug 1 | Fully hierarchical, max depth 8 | 0 |
| `Issues-FS__Service__UI` | 49 | 22 | 9 types incl. release, user-story, cli | Mixed `data/` + `issues/` | 0 |
| `Issues-FS` | 24 | 0 | task 16, bug 8 | `data/` | **3** |
| `Issues-FS__CLI` | 3 | 0 | task, feature, bug | `data/` | 0 |
| `Issues-FS__Docs` / `__Dev` / `__Dev__Utils` | 0 | 0 | — | config scaffolding only | 0 |

**Ecosystem total: 147 nodes across four graphs.**

**The SGraph Send graph is the specimen to publish.** Schema-complete (all 13 `Schema__Node` fields on all 71 nodes), deeply hierarchical, real content, root `Repo-1` = *"SGraph Send — Zero-Knowledge Encrypted File Sharing"*, authored 2026-02-08 → 2026-02-22. Statuses: done 21, backlog 21, pending 14, in-progress 8, deferred 4, active 2, confirmed 1. Top tags: frontend 17, ui 17, incident-handling 16, api 15, backend 14.

⚠️ **Index staleness is real and worth narrating.** `Issues-FS/.issues/_index.json` declares `total_issues: 22` with 6 bugs; on disk there are **24 issues and 8 bugs**. The SGraph Send graph has **no `_index.json` at any level** — and works fine, because the CLI walks the tree. That is an honest argument for the design: the index is a cache, not a source.

---

## 10. Storage backends

`issues_fs/schemas/enums/Enum__Graph__Storage__Backend.py`:

```python
MEMORY     = "memory"        # In-memory (tests)
LOCAL_DISK = "local_disk"    # Local file system
SQLITE     = "sqlite"        # SQLite database
ZIP        = "zip"           # ZIP archive
```

Four backends, all real, all constructed via `Graph__Repository__Factory` over the memory-fs abstraction.

⚠️ **S3 is claimed in four places** — `Issues-FS/README.md`, `Issues-FS__Dev/README.md`, `.claude/CLAUDE.md`, and the architecture overview — **and does not exist.** memory-fs 0.41.0 ships no S3 provider. Only `docs/issues_fs/architecture/0.41.0__issues-fs__memory-fs-abstraction-layer.md` gets this right.

---

## 11. Test counts

| Repo | Test files | Test functions | Test LOC |
|---|---|---|---|
| **Issues-FS** | 45 | **604** | 8,213 |
| **Issues-FS__CLI** | 7 | **94** | 962 |
| Issues-FS__Dev__Utils | 4 | 19 | 131 |
| Issues-FS__Service__UI | 2 | 3 | 277 |
| Issues-FS__Service | 1 | 3 | 23 |
| Issues-FS__Service__Client__Python | 1 | 3 | 23 |

⚠️ `Issues-FS/README.md` claims "475+ test methods across 36 test files"; `Issues-FS__Dev/README.md` claims "552+". Both are behind. **The measured number is 604.**

---

This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).