[nightshift] doc-drift: documentation out of sync with codebase

[nightshift-micr]

Documentation Drift Analysis — Microck/ancla

Automated by Nightshift v3 (GLM 5.1).

Compared README.md, CHANGELOG.md, docs/, and ios/README.md against actual source code in ios/.

---

P1 — README describes single anchor, but code supports multiple

Files: README.md (lines 8, 23, 43, 54, 77) vs ios/ancla-shared/ancla-models.swift (line 270)

The README repeatedly describes pairing a single NFC anchor:

• "a physical-release iphone blocker built around one paired nfc anchor" (line 8)
• "you pair one nfc anchor" (line 23)
• "pairs one physical nfc anchor to the device" (line 43)
• "you pair a single ntag213 sticker to the app" (line 54)

But the data model stores multiple anchors in an array:

var pairedTags: [PairedTag] = []

The CHANGELOG confirms this feature was added:

"Support multiple paired anchors (3aaa6a4)"

Impact: Users and contributors get an incorrect understanding of the app's capabilities.

Recommendation: Update README to describe multi-anchor support: "pair one or more nfc anchors," "scan any paired anchor to release," etc.

---

P2 — README missing three major features from April 2026

The CHANGELOG and source code implement these features, but the README's "what it does" section does not mention them:

1. Scheduled sessions (CHANGELOG: "Add scheduled sessions on iphone")

• Source: schedule-editor-view.swift, ScheduledSessionPlan model, scheduledPlans array
• Users can schedule blocking sessions in advance

2. Emergency unbrick (CHANGELOG: "Add emergency unbricks for active sessions")

• Source: emergency/unbrick references in app-view-model.swift, content-view.swift, lock-screen-view.swift, ancla-core.swift
• Provides an escape hatch for stuck sessions

3. Usage history (CHANGELOG: "Add usage history for completed sessions")

• Source: history references in app-view-model.swift, content-view.swift, ancla-core.swift, ancla-models.swift
• Tracks completed blocking sessions

Impact: Users reading the README don't know these features exist.

Recommendation: Add to the "what it does" list:

• "supports scheduled sessions with configurable start times"
• "provides emergency unbrick for stuck sessions"
• "tracks usage history for completed sessions"

---

P2 — README repo layout and architecture diagram incomplete

File: README.md — "repo layout" and "architecture" sections

Missing from the layout:

• fonts/ directory (Google Sans Flex font files, mentioned in release checklist)
• No note that ios/ contains an ancla-lite/ target with its own CI workflow

The architecture diagram shows 3 layers but doesn't mention:

• ancla-lite target (sideload fallback without shield extension)
• ancla-core SPM package (already mentioned in prose but not in the diagram)
• Test targets (ancla-core-tests, ancla-tests)

Recommendation: Add a note about the lite target and update the tree to include fonts/.

---

P2 — release-checklist.md missing verification for new features

File: docs/release-checklist.md

The checklist has thorough QA steps for the original feature set (NFC pairing, mode editing, shield extension) but doesn't include verification steps for:

1. Scheduled sessions: No step to verify schedule creation, editing, deletion, or auto-arm behavior
2. Emergency unbrick: No step to verify the unbrick flow works correctly for stuck sessions
3. Usage history: No step to verify history tracking accuracy and display
4. Multiple anchors: No step to verify pairing/using a second anchor, or releasing with a non-primary anchor

Recommendation: Add dedicated QA sections for each new feature.

---

P3 — docs/sideloading.md missing third workflow

File: docs/sideloading.md

The document describes two workflows:

• .github/workflows/ios-sideload-ipa.yml
• .github/workflows/ios-sideload-lite-ipa.yml

But a third workflow exists:

• .github/workflows/ios-full-unsigned-ipa.yml

This workflow is not documented in the sideloading guide.

---

P3 — ios/README.md hardcoded development paths

File: ios/README.md (lines 33, 45)

Contains hardcoded paths specific to one developer's machine:

cd /home/ubuntu/workspace/ancla
cd /home/ubuntu/workspace/ancla/ios

These won't work for other contributors.

Recommendation: Use relative paths or placeholder like cd /path/to/ancla.

---

P3 — docs/full-sideload-experiment.md has internal git commands

File: docs/full-sideload-experiment.md (lines 18-28)

Contains a full git add && git commit && git push command block with redacted author info (GIT_AUTHOR_NAME="***"). This looks like operator notes committed to the repo rather than user-facing documentation.

Recommendation: Replace with general instructions ("commit your changes and push to the target branch") or move to a private operator guide.

---

Summary

Severity	Count	Key Issues
P1	1	README says single anchor, code supports multiple
P2	3	Missing features, incomplete layout, incomplete checklist
P3	3	Missing workflow doc, hardcoded paths, internal git commands
Total	7

Highest impact fix: Update the README's anchor description from singular to plural (P1), then add the three missing features to the "what it does" section (P2).