docs: audit links, glossary, readability pass #2

Open

eSlider wants to merge 9 commits from docs/improvement into main

pull from: docs/improvement

merge into: :main

:main

:feat/prototype-swarm-patrol

:docs/live-demo-links

:docs/improvement

Conversation 2 Commits 9 Files Changed 35

+1028 -192

eSlider commented 2026-07-10 10:47:10 +01:00

Owner

Copy Link

Copy Source

Summary

Documentation audit: glossary T0–T4 and source of truth, fixed links and factual drift (pose frame, offload tooling), README readability, live demo links, improvement records under docs/improvement/.

• Closes Auto-analyse links, text, improvements, readability (#1)

Test plan

• Relative markdown link check (33 files)
• CI verify job green

## Summary Documentation audit: glossary T0–T4 and source of truth, fixed links and factual drift (pose frame, offload tooling), README readability, live demo links, improvement records under `docs/improvement/`. - Closes #1 ## Test plan - [x] Relative markdown link check (33 files) - [ ] CI verify job green

eSlider added 1 commit 2026-07-10 10:47:10 +01:00

docs: audit links, glossary T0-T4, readability pass ... 5f6fd8462c

Extend glossary with storage floors, source of truth, and linkable anchors.
Fix broken links, pose frame drift, rsync/offload wording, and README tone.
Add docs/improvement audit records and live demo links in design journey.

eSlider added 1 commit 2026-07-10 10:48:30 +01:00

fix(ci): fetch PR ref on checkout instead of shallow main clone ... 9bec50e8f7

Shallow clone of default branch did not contain commits on feature
branches, causing pull_request verify jobs to fail at checkout.

eSlider referenced this pull request 2026-07-10 10:49:12 +01:00

Auto-analyse links, text, improvements, readability #1

eSlider commented 2026-07-10 10:49:12 +01:00

Author

Owner

Copy Link

Copy Source

CI was red on first push: checkout step used shallow clone of main, so PR commit was not in history.

Fixed in 9bec50e — fetch ${{ gitea.ref }} then checkout FETCH_HEAD.

Status: Verify simulator + Trivy scan passing on 9bec50e.

CI was red on first push: checkout step used shallow clone of `main`, so PR commit was not in history. Fixed in `9bec50e` — fetch `${{ gitea.ref }}` then `checkout FETCH_HEAD`. **Status:** Verify simulator + Trivy scan passing on `9bec50e`.

eSlider commented 2026-07-10 10:50:26 +01:00

Author

Owner

Copy Link

Copy Source

PR review — checked against issue #1 acceptance criteria

Reviewed 9bec50e as reviewer. CI: Verify simulator + Trivy green after checkout fix.

---

Verdict

Approve for merge as documentation delivery — strong manual audit, glossary, link fixes, live demo links, docs/improvement/ records.

Do not treat as complete closure of issue #1 — none of the four automation acceptance criteria are implemented yet. Recommend either:

• change PR footer from Closes #1 → Relates to #1 and keep the issue open for automation follow-up, or
• merge and immediately reopen / spawn a child issue for CI checks only.

---

Issue #1 acceptance criteria

Criterion	Status	Evidence
Link checker in CI for docs/, infra/, READMEs	Not met	No workflow step or script added. Manual Python pass documented in docs/improvement/2026-07-10-audit.md only.
Glossary anchor validation for #term links	Not met	No CI validation. Audit: 102 glossary links, 0 broken anchors, but 24 links land on section headers (#swarm--robotics, #infrastructure--delivery, #data--storage) instead of term-specific ### anchors — e.g. Zenoh, C2, CRDT, GPS-denied in 04, 10, 01.
Optional readability pass (terminology lint, US spell-check)	Partial	Manual caveman README pass + US spelling fixes (behavior). No automated lint.
Report artifact or PR comment on failure	Not met	No CI job emits link/anchor report on failure.

---

What this PR delivers well

• Glossary: T0–T4, source of truth, layers, bulk sync/offload — 15 linkable ### headings.
• Links: broken 03-storage-design.md fixed; 33 markdown files, 0 broken relative .md links (manual check).
• Factual: pose frame 46 bytes / ASCII drone_id aligned with broadcast.py + sim.ts.
• Terminology: pipeline stages vs storage floors disambiguated in design journey §4.
• Tooling docs: rsync / mc mirror / cp -ru roles consistent.
• Live demos: prototype, SQL explorer, Grafana dashboard linked in journey.
• Bonus fix: CI checkout now git fetch origin ${{ gitea.ref }} — fixes PR branch checkout (fatal: reference is not a tree). Worth keeping regardless of docs.

---

Remaining doc debt (non-blocking)

Item	Notes
Glossary table terms	Still no per-row anchors; many links jump to section top
T4 ordering in glossary	Source of truth sits between T3 and T4
schemas/ / DuckLake	Documented in OQ §13–§14, not implemented
GitOps “source of truth” vs data SSOT	Different meanings in 11-cicd-delivery — clarify later
push paths-ignore: docs/**	Docs-only pushes to main skip verify; PRs to main still run full CI

---

Suggested follow-up (issue #1 or new PR)

1. Add scripts/check_docs_links.py + CI job docs-verify on pull_request (and optionally drop paths-ignore for docs on push).
2. Extend glossary with ### per table term or fail CI when #swarm--robotics-style section links are used for named terms.
3. On failure: post workflow summary / PR comment with broken link list.

---

Summary: merge recommended for doc improvements + CI checkout fix. Issue #1 automation AC still open — adjust Closes #1 wording unless automation lands in same PR.

## PR review — checked against issue #1 acceptance criteria Reviewed `9bec50e` as reviewer. CI: **Verify simulator** + **Trivy** green after checkout fix. --- ### Verdict **Approve for merge as documentation delivery** — strong manual audit, glossary, link fixes, live demo links, `docs/improvement/` records. **Do not treat as complete closure of issue #1** — none of the four automation acceptance criteria are implemented yet. Recommend either: - change PR footer from `Closes #1` → `Relates to #1` and keep the issue open for automation follow-up, **or** - merge and immediately reopen / spawn a child issue for CI checks only. --- ### Issue #1 acceptance criteria | Criterion | Status | Evidence | | --- | --- | --- | | Link checker in CI for `docs/`, `infra/`, READMEs | **Not met** | No workflow step or script added. Manual Python pass documented in `docs/improvement/2026-07-10-audit.md` only. | | Glossary anchor validation for `#term` links | **Not met** | No CI validation. Audit: 102 glossary links, 0 broken anchors, but **24 links land on section headers** (`#swarm--robotics`, `#infrastructure--delivery`, `#data--storage`) instead of term-specific `###` anchors — e.g. Zenoh, C2, CRDT, GPS-denied in `04`, `10`, `01`. | | Optional readability pass (terminology lint, US spell-check) | **Partial** | Manual caveman README pass + US spelling fixes (`behavior`). No automated lint. | | Report artifact or PR comment on failure | **Not met** | No CI job emits link/anchor report on failure. | --- ### What this PR delivers well - **Glossary:** T0–T4, source of truth, layers, bulk sync/offload — 15 linkable `###` headings. - **Links:** broken `03-storage-design.md` fixed; 33 markdown files, 0 broken relative `.md` links (manual check). - **Factual:** pose frame 46 bytes / ASCII `drone_id` aligned with `broadcast.py` + `sim.ts`. - **Terminology:** pipeline stages vs storage floors disambiguated in design journey §4. - **Tooling docs:** rsync / `mc mirror` / `cp -ru` roles consistent. - **Live demos:** prototype, SQL explorer, Grafana dashboard linked in journey. - **Bonus fix:** CI checkout now `git fetch origin ${{ gitea.ref }}` — fixes PR branch checkout (`fatal: reference is not a tree`). Worth keeping regardless of docs. --- ### Remaining doc debt (non-blocking) | Item | Notes | | --- | --- | | Glossary table terms | Still no per-row anchors; many links jump to section top | | T4 ordering in glossary | `Source of truth` sits between T3 and T4 | | `schemas/` / DuckLake | Documented in OQ §13–§14, not implemented | | GitOps “source of truth” vs data SSOT | Different meanings in `11-cicd-delivery` — clarify later | | `push` `paths-ignore: docs/**` | Docs-only pushes to `main` skip verify; PRs to `main` still run full CI | --- ### Suggested follow-up (issue #1 or new PR) 1. Add `scripts/check_docs_links.py` + CI job `docs-verify` on `pull_request` (and optionally drop `paths-ignore` for docs on push). 2. Extend glossary with `###` per table term **or** fail CI when `#swarm--robotics`-style section links are used for named terms. 3. On failure: post workflow summary / PR comment with broken link list. --- **Summary:** merge recommended for doc improvements + CI checkout fix. Issue #1 automation AC still open — adjust `Closes #1` wording unless automation lands in same PR.

eSlider added 1 commit 2026-07-10 10:54:29 +01:00

feat: add CI documentation rules checker and docs-verify job ... e6e57843cb

Enforce link resolution, glossary anchors, and readability rules on every
push and PR; docs-only pushes to main still run docs-verify while skipping
the simulator gate.

eSlider added 1 commit 2026-07-10 10:56:14 +01:00

docs: default caveman style for issues, PRs, and reviews ... bed6f93626

Document caveman-full as the collaboration voice in AGENTS and CONTRIBUTING,
and add Gitea issue/PR templates that pre-fill terse structure.

eSlider added 1 commit 2026-07-10 10:57:44 +01:00

fix: revert ADR edits and enforce immutable accepted records ... 10a18f1321

Restore docs/adr to main; add check_adrs.py CI gate so existing ADR-*.md
files cannot be modified — supersede with a new numbered ADR instead.

eSlider added 1 commit 2026-07-10 10:59:23 +01:00

refactor: move scripts/ to bin/ ... b4de3ed076

Relocate check_docs, check_adrs, and docs_rules; update CI, tests, and docs.

eSlider added 1 commit 2026-07-10 10:59:32 +01:00

chore: drop unrelated files from bin/ move commit df04736336

eSlider added 1 commit 2026-07-10 11:02:57 +01:00

fix: drop PyYAML dep so verify job pytest passes ... 826cef0c3e

Store doc rules in bin/docs_rules.json (stdlib json). test_check_docs no
longer fails in the simulator job that only installs simulator/requirements.txt.

eSlider referenced this pull request 2026-07-10 12:18:32 +01:00

docs: live demo external links in design journey #3

eSlider added 1 commit 2026-07-10 12:18:51 +01:00

docs: move live demo links to PR #3 ... 302de4024d

Drop duplicate external URLs from design journey; small PR #3 owns them.

All checks were successful

Hide all checks

CI & Release / Verify documentation (push) Skipped

CI & Release / Verify simulator (push) Skipped

CI & Release / Trivy scan (push) Skipped

CI & Release / Semantic Release (push) Skipped

CI & Release / Verify documentation (pull_request) Successful in 4s

Details

CI & Release / Verify simulator (pull_request) Successful in 11s

Details

CI & Release / Trivy scan (pull_request) Successful in 9s

Details

CI & Release / Semantic Release (pull_request) Skipped

Details

This pull request has changes conflicting with the target branch.

• README.md
• docs/02-architecture.md
• docs/03-data-platform.md
• docs/04-swarm-sync.md
• docs/06-environments.md
• docs/08-roadmap.md
• docs/09-open-questions.md
• docs/12-design-journey.md

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin docs/improvement:docs/improvement

git checkout docs/improvement

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

andrea eSlider (Andrey)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: eSlider/swarm-house#2