docs: reconcile template docs and optional-auth story

[valorengels]

Reconciles the template's documentation with its actual source-bearing state and documents the optional-auth + LAN-cleartext stories.

Changes

• CLAUDE.md: rewrite Repository Overview + Project Structure to describe the implemented lib/ tree (core, features, shared, l10n, main.dart); drop "documentation-only"/"no source code" framing and the "When Implemented" framing.
• CLAUDE.md + docs/architecture.md: add an Optional Authentication section — how to enable (implement AuthRepository, uncomment the DI block in injection.dart) and how to strip (delete lib/core/auth/ + test/core/auth/, remove AuthTokenManager wiring from injection.dart/DioClient/RequestExecutor, delete auth_interceptor.dart/auth_token_manager.dart, clear the auth_exception.dart/offline_queue.dart reference).
• docs/setup_reference.md: add a network-security-config pattern for LAN apps — base-config cleartextTrafficPermitted="true" + manifest android:networkSecurityConfig wiring + per-domain domain-config alternative + security tradeoff note.

Docs only; no code, DI, or Android file changes.

Closes #15

[valorengels]

Review: Changes Requested

The three deliverables land cleanly: CLAUDE.md is rewritten to describe the source-bearing template (no more "documentation-only" / "no source code"), the Optional Authentication section documents enable + strip, and docs/setup_reference.md adds the network-security-config pattern for LAN apps with the security tradeoff. All three plan Verification rows pass on this branch, and the plan's No-Gos are respected (docs only, no committed network_security_config.xml, no auth DI wiring).

One blocker: the documented strip-auth closure is incomplete. It instructs deleting lib/core/auth/ but omits lib/core/routes/auth_guard.dart, which imports ../auth/auth_bloc.dart and ../auth/auth_state.dart. Following the strip verbatim leaves auth_guard.dart with unresolvable imports — flutter analyze / the build break. This contradicts the plan's claim (docs/plans/docs_auth_reconcile.md, Technical Approach) that the closure was "verified against the actual source so following it verbatim compiles." The prior critique rounds caught auth_interceptor.dart, request_executor.dart, and the offline_queue.dart/auth_exception.dart reference but missed auth_guard.dart.

Rubric

• 1. Plan vs. implementation match — fail — the plan promises a compile-verified strip closure; the documented closure omits lib/core/routes/auth_guard.dart, a live consumer of lib/core/auth/, so the strip does not compile.
• 2. New code quality — n/a — docs only.
• 3. Test coverage — n/a — docs only.
• 4. Regression risk to existing callers — n/a — docs only.
• 5. Data integrity — n/a — no schema/data changes.
• 6. Security — pass — no code added; the netsec section correctly warns against global cleartext and offers the per-domain alternative.
• 7. Documentation accuracy — fail — strip closure omits auth_guard.dart; otherwise CLAUDE.md / netsec docs are accurate against the source.
• 8. PR body accuracy — pass — body claims (3 files, docs-only, no code/DI changes) match the diff.
• 9. Disclosed deferrals — pass — no deferral disclosures in the PR body.
• 10. Follow-up claims verified — pass — no follow-up claims to verify.

Pre-Verdict Checklist

• 1. All plan acceptance/success criteria validated against diff — FAIL — strip closure incomplete (auth_guard.dart).
• 2. No-Gos from plan — none violated — PASS — docs only; no netsec file committed; no auth DI change.
• 3. New except Exception blocks — N/A — docs only.
• 4. New integration tests exercise serialization boundary — N/A — docs only.
• 5. Plan internal consistency — spike findings match task steps — PASS.
• 6. No hardcoded secrets or debug artifacts — PASS — no secrets in docs.
• 7. New public APIs — docstrings present — N/A.
• 8. Breaking changes — migration path documented — N/A.
• 9. Tests added for new behavior — N/A — docs only.
• 10. Tests cover the failure path — N/A.
• 11. UI changes — screenshot captured — N/A — no UI files.
• 12. Docs updated for user-facing changes — PASS — docs are the deliverable.

Blockers

• docs/architecture.md (Optional Authentication → Strip) + CLAUDE.md (Optional Authentication → Strip) — the strip closure omits lib/core/routes/auth_guard.dart, which imports lib/core/auth/auth_bloc.dart and lib/core/auth/auth_state.dart (verified lines 3-4). Deleting lib/core/auth/ as instructed leaves auth_guard.dart with unresolvable imports, so the strip does not compile — contradicting the plan's "following it verbatim compiles" claim. auth_guard.dart is orphaned (only a commented-out import in app_router.dart:8), so the fix is to add it to the closure. Severity: blocker. Fix: add "delete lib/core/routes/auth_guard.dart" to both strip instructions; optionally note the stale commented auth references in lib/core/routes/app_router.dart (lines 5-20).

Tech Debt

• None

Nits

• None

Miscellaneous

• None

Acknowledged Deferrals (verified)

• None

Verification Results

• V1 grep -n "documentation-only\|no source code" CLAUDE.md — exit 1 (no matches) — pass
• V2 grep -rn "AuthRepository\|AuthBloc" CLAUDE.md docs/architecture.md — exit 0 — pass
• V3 grep -rn "network_security_config\|cleartextTrafficPermitted" docs/ — exit 0 — pass

Screenshots

None (docs-only; no UI changes).

[valorengels]

Review: Approved (re-review after patch)

Re-review of the single blocker from the prior round. Patch commit ba7016d adds lib/core/routes/auth_guard.dart to both strip-auth closures (CLAUDE.md Optional Authentication → Strip and docs/architecture.md Optional Authentication → Strip), plus a note on the stale commented auth references in lib/core/routes/app_router.dart.

Blocker resolution verified against source:

• lib/core/routes/auth_guard.dart exists and imports ../auth/auth_bloc.dart (line 3) and ../auth/auth_state.dart (line 4) — a live consumer of lib/core/auth/, so deleting lib/core/auth/ without it left unresolvable imports. Both closures now include deleting it.
• The only remaining consumers of lib/core/auth/ are test/core/auth/auth_bloc_test.dart (already in the closure via test/core/auth/), and commented references in injection.dart / app_router.dart (the latter now explicitly noted as cleanable). Following the closure verbatim now compiles.

Re-verified clean:

• All three plan Verification rows pass on PR head ba7016d: V1 no "documentation-only"/"no source code" (exit 1); V2 auth optionality present (exit 0); V3 network-security-config/cleartextTrafficPermitted present (exit 0).
• Docs-only; no code, DI, or Android file changes. No-Gos respected (no committed network_security_config.xml, no auth DI wiring).

Rubric

• 1. Plan vs. implementation match — pass — strip closure now complete; auth optionality, netsec pattern, and CLAUDE.md rewrite all match the plan's Technical Approach.
• 2. New code quality — n/a — docs only.
• 3. Test coverage — n/a — docs only.
• 4. Regression risk to existing callers — n/a — docs only.
• 5. Data integrity — n/a — no schema/data changes.
• 6. Security — pass — no code; netsec section correctly warns against global cleartext and offers per-domain alternative.
• 7. Documentation accuracy — pass — strip closures and all file/line references verified against actual source.
• 8. PR body accuracy — pass — body claims (3 files, docs-only) match the diff.
• 9. Disclosed deferrals — pass — none.
• 10. Follow-up claims verified — pass — none.

Pre-Verdict Checklist

• 1. All plan acceptance/success criteria validated against diff — PASS — all three Success Criteria hold.
• 2. No-Gos from plan — none violated — PASS.
• 3-5, 7-11. N/A — docs only, no code/tests/UI.
• 6. No hardcoded secrets or debug artifacts — PASS.
• 12. Docs updated for user-facing changes — PASS — docs are the deliverable.

Blockers

• None

Tech Debt

• None

Nits

• None

Miscellaneous

• None

Verification Results

• V1 grep -n "documentation-only\|no source code" CLAUDE.md — exit 1 (no matches) — pass
• V2 grep -rn "AuthRepository\|AuthBloc" CLAUDE.md docs/architecture.md — exit 0 — pass
• V3 grep -rn "network_security_config\|cleartextTrafficPermitted" docs/ — exit 0 — pass

Screenshots

None (docs-only; no UI changes).

[valorengels]

RE-REVIEW at new head (DOCS stage commit f60d69c) — APPROVED.

Verified the DOCS-stage cascade commit f60d69c is a sound docs-only change:

• Full PR diff (main...f60d69c) touches 5 files, all docs: CLAUDE.md, docs/architecture.md, docs/setup_reference.md, docs/sphinx/source/index.rst, docs/sphinx/source/overview.md. No code changes.
• docs/sphinx/source/overview.md + index.rst now describe the source-bearing template and drop the retired 'documentation-only' / 'no source code' / 'When Implemented' framing. No stale terms remain in docs/sphinx (grep exit 1).
• Cascade is consistent with the source-bearing CLAUDE.md framing landed in the earlier BUILD stage.

All three plan Success Criteria hold at f60d69c; all three plan Verification greps pass. Docs-only; no code changes. APPROVED.