Spec: F46 — README & Documentation Cleanup / Alignment

Status: shipped with Contract Graph evidence boundary (2026-07-15)

1. Problem & CEO Job

Job: Trust the signal — a GitHub README branded “Trợ Lý Lumi,” an iOS README describing a senior mail-scanning app, and an Android “Now in Android” template mislead developers, investors, and new hires.

This spec aligns READMEs, platform docs, and document headings with Lumi AI Workspace. It adds no new documentation or content strategy.

Strategic position (v2, 2026-06-14): “AI Workspace” is valid internal architecture language under competitive-strategy-v2.md §18, not first-market positioning. The first-market story remains the vertical SME operating stack for Vietnam fit-out, renovation, and small M&E contractors; “CEO brief” means the owner’s daily operating brief. Customer-facing copy must not lead with “AI Workspace” (§14.1; e.g. F22); that rule does not govern these internal READMEs. This reframes intent, not strings.

2. User Stories & Acceptance Criteria

• As a developer cloning the repo, I want the root README to immediately tell me this is Lumi AI Workspace, so that I know I’m in the right place in under 5 seconds.

  • README.md heading is # Lumi AI Workspace.
  • First paragraph describes Lumi AI Workspace — the CEO brief product, not a mail-scanning app.
  • No occurrences of “Trợ Lý Lumi” or “Lumi Assistant” in the file.

• As an iOS developer opening the iOS folder, I want the iOS README to describe the Lumi iOS app, so that I’m not reading about a completely different product.

  • ios/README.md heading is # Lumi AI Workspace — iOS.
  • Content describes the Lumi mobile client (F30): daily pulse, CEO brief, tasks, chat — not mail scanning.
  • Project structure reflects the actual Lumi iOS codebase, not the WTM mail-scanning app.
  • Requirements: iOS 17+, Xcode 16+ (matching actual project config).
  • No references to VisionKit, document scanning, OCR, or mail-related features.

• As an Android developer opening the Android folder, I want the Android README to describe the Lumi Android app, so that I’m not reading Google’s sample app docs.

  • android/README.md heading is # Lumi AI Workspace — Android.
  • All “Now in Android” references removed.
  • All Google Play store links replaced with Lumi’s actual listing (or removed if not published yet).
  • Content describes actual Lumi features, architecture, and build instructions.
  • android/app/README.md updated if it exists with stale content.

• As a developer reading iOS documentation, I want all iOS docs to reference “Lumi AI Workspace,” so that every file speaks with one brand voice.

  • ios/SECURITY.md: heading + content updated. References to “mail never leaves your iPhone” replaced with actual Lumi security posture.
  • ios/CONTRIBUTING.md: heading updated to “Contributing to Lumi AI Workspace — iOS”.
  • ios/SKILL.md: description updated from “Lumi Assistant” to “Lumi AI Workspace iOS app.”
  • ios/CODE_EXAMPLES.md: heading updated.
  • ios/QUICKREF.md: heading updated.

• As a doc maintainer, I want a documentation drift check in CI, so that stale product names are caught before they reach main.

  • CI check greps for forbidden strings: “Trợ Lý Lumi”, “Lumi Assistant”, “Now in Android” (in docs, with exclusions for archive/plan/audit dirs that reference old strings historically).
  • Every pull request targeting main is covered. The shipped workflow currently targets deploy/backend*; this remains an explicit Contract Graph gap.

3. Scope Boundaries

• In:
  • README.md (root) — heading + first paragraph + any stale references.
  • ios/README.md — complete rewrite to describe the Lumi iOS app.
  • android/README.md — complete rewrite to describe the Lumi Android app.
  • android/app/README.md — check + rewrite if stale.
  • ios/SECURITY.md — update product name + security posture description.
  • ios/CONTRIBUTING.md — update heading.
  • ios/SKILL.md — update heading + description.
  • ios/CODE_EXAMPLES.md — update heading.
  • ios/QUICKREF.md — update heading + command references.
  • CI check for forbidden strings in docs, with its current branch-trigger boundary recorded explicitly.
• Out:
  • Writing new documentation content beyond the cleanup scope.
  • Cosmetic updates to files that are already correct (“Lumi AI Workspace”).
  • ios/DerivedData/, reference/, backend/venv/ — generated/third-party files.
  • docs/archive/WTM/ — historical archive, not active docs.
  • Android .kt files with “Now in Android” in code comments — out of scope (50 occurrences in android/core/designsystem/; deferred to separate code cleanup spec — see §12).
  • DESIGN.md, DIAGRAM.md, monorepo.md — covered by F41.

4. Data Model

No model changes.

5. API Contract

No API changes.

6. UI / UX

No application UI changes.

7. Test Plan

8. Current Behavior

Shipped 2026-06-12. All active platform docs reflect “Lumi AI Workspace.” Root README, iOS README, Android README, and 5 iOS doc files were rewritten. The CI source contains the forbidden-string check with appropriate archive exclusions, but its current branch filter does not prove every main pull request runs it.

Before (2026-06-11):

• README.md line 1: # Trợ Lý Lumi
• ios/README.md: described a mail-scanning senior-care app (WTM product, VisionKit OCR, Gemma 4 E2B AI, subscription paywall)
• android/README.md: Google’s “Now in Android” sample app template, Google Play badge for com.google.samples.apps.lumi
• 5 iOS docs (SECURITY.md, CONTRIBUTING.md, SKILL.md, CODE_EXAMPLES.md, QUICKREF.md): all said “Lumi Assistant”
• ios/SECURITY.md: claimed “Your mail never leaves your iPhone” (mail-scanning posture, not Lumi)
• No CI forbidden-string check for “Now in Android”

9. Error States

• If the forbidden-string gate blocks an intentional historical reference, narrow the scope or add a documented exclusion rather than weakening the pattern.
• If a platform README claims features that do not exist on that platform yet, treat it as a documentation bug even if the backend feature exists elsewhere.

10. Diagrams & Docs Touched

• Root README.md
• Platform docs: ios/README.md, ios/SECURITY.md, ios/CONTRIBUTING.md, ios/SKILL.md, ios/CODE_EXAMPLES.md, ios/QUICKREF.md
• android/README.md, android/app/README.md
• CI: .github/workflows/ci-docs.yml (forbidden-string step extended)

11. Implementation Audit (2026-06-14)

Gaps flagged:

• Kotlin code comment drift (claim 8): 50 “Now in Android” occurrences in Android design-system code comments persist. Not user-facing, not in docs, but a future developer reading the design system code still sees Google’s sample app identity. Low severity; track in separate spec.
• iOS README F30 feature parity: iOS README now describes all F30 features, but F30 is still 🚧 (in progress). If F30 features are removed from the iOS app, the README drifts again. Requires a same-PR rule: iOS feature changes must update ios/README.md.

12. Open Questions / Decisions

1. iOS README rewrite scope: Describe what shipped and what’s planned, referencing F30 spec. Don’t claim features that don’t exist. (Decision: done — bug log 2026-06-12)
2. Android README content depth: Minimal README with build instructions + pointer to main docs. Android architecture docs can live in android/docs/ if needed later. (Decision: done — bug log 2026-06-12)
3. “Now in Android” in Kotlin comments: 50 occurrences in android/core/designsystem/ — out of scope for this spec. Those are code comments in a design system forked from NIA. Separate code cleanup spec handles that.

13. Bug / Change Log

2026-06-14 — Strategy v2 realignment (positioning)

Type: Documentation Change

Summary:

• Added a “Strategic position (v2)” note to §1 clarifying intent: the “AI Workspace” architecture label is fine in these internal READMEs (strategy v2 §18), but the product’s first-market story is the vertical SME operating stack for Vietnam contractors, and “CEO brief” should read as the owner’s daily operating brief for that vertical. No string rewrites prescribed — light-touch, internal-docs alignment.

Reason: competitive-strategy-v2.md §18 (“AI Workspace” = internal architecture label; “CEO Morning Brief → Owner daily operating brief”) and §14.1 (customer-facing copy must not lead with “AI Workspace”), plus the MVP_SCOPE.md “Positioning doctrine (strategy v2, 2026-06-14)”.

Impact: Positioning prose only. No data model, API, route, test, or status change. No product rename; brand-name strings stay “Lumi AI Workspace” per F41.

Tests: python3 -m unittest scripts.tests.test_f46_readme_alignment proves the active README headings, replaced-identity absence, and workflow guard source. It does not prove hosted execution on main.

Notes: The first-market positioning lives on marketing surfaces (F22), not these internal READMEs.

2026-06-14 — Restructure to TEMPLATE.md section order; ACs checked (SP fleet)

Type: Documentation Change

Summary:

• Status corrected from incorrect draft state to “shipped (2026-06-12)”.
• All ACs checked [x] (confirmed by bug log below).
• Renumbered sections to match TEMPLATE.md order (§8 Current Behavior, §9 Error States, §10 Diagrams, §11 Implementation Audit, §12 Open Questions, §13 Bug Log).
• Added §11 audit table (8 claims: 7 ✅ match, 1 deferred).
• Absorbed §10 Edge Cases into §11 gaps.

2026-06-12 — Full documentation cleanup implemented

Type: Feature

Summary:

• Rewrote README.md: brand name, Known Limitations updated for F35 email + F29 chat.
• Rewrote ios/README.md: replaced mail-scanning “Lumi Assistant” description with actual feature list (Daily Pulse, CEO Brief, Today Dashboard, Tasks & Projects, Commitments, Risks & Decisions, Internal Chat, Signal Inbox); corrected project structure and spec links.
• Rewrote android/README.md: replaced “Now in Android” template with Lumi Android description; fixed spec link.
• Rewrote ios/SECURITY.md: removed on-device OCR/mail-scanning claims, framed iOS app as a thin SaaS client over HTTPS, documented Keychain-based token storage via JWTStorage.
• Updated ios/CONTRIBUTING.md, ios/SKILL.md, ios/CODE_EXAMPLES.md, ios/QUICKREF.md brand headings.
• Extended CI “Forbidden strings in documentation” check to cover “Now in Android” with exclusions for archive/plan/audit docs that intentionally reference old strings historically; the guard now lives in .github/workflows/ci-docs.yml.

Tests:

• CI forbidden-string check covers all patterns.