Epic: Reproduce, sync, and serve Docs with preserved navigation and anchors

Parent epic: #4

Normative authority:

• Spec 03 — Docs source ownership and adapter
• Spec 03 — public provenance boundary
• Spec 02 — URL/link/fragment/SEO compatibility
• #35 supplies the generic compatibility gate; #38 owns direct-sync ingestion/management; #44 owns unified search.

Product outcome

Serve the authoritative DataTalksClub/docs corpus through deterministic, source-bound Django read models while preserving exact pretty URLs, explicit permalinks, navigation order and hierarchy, breadcrumbs, heading anchors, safe relative links/assets, accessible Markdown features, modification provenance for management, and section-level search behavior.

Public pages must not render repository names, source revisions/checksums/paths, modification provenance, source links, or edit-on-GitHub links. Those values remain available only to build, audit, Studio, and admin workflows. This supersedes the old title, acceptance criterion, and Playwright scenario that required a public edit link.

Current-state census at origin/main@face8e4808d65afbf0374d1ced7a88079950d663

The existing public renderer is a checked baked projection, not an accepted #41 source adapter or live cutover:

• declared Docs source: 3f23e006ffdaa498bbc69697408853b6f5eb37dc, tree 585e440a6c7c32e8a3936f431a8c0a1d8709b1a7;
• source tree: 285 blobs, 119 Markdown, 54 images;
• checked projection: 106 pages, 39 images, 381,637 bytes, SHA-256 15d9491fee4683303ce3cc0ba00c702599016149c010923e200a85d37084fc8a;
• checked asset-manifest digest: 8cce1dd8b6d0339c42879817cfa9d07f45684c9084ac7445dec3c8f6056f601f;
• current compatibility scope: 174 all-preserve rows—107 HTML, 63 assets, two JSON, and two XML;
• only 145 projection records represent that scope, leaving 29 public compatibility paths without an implemented/approved disposition;
• the old audit digest 1abd84ab... is stale, and the checked projection contains at least one declared-source/body contradiction in courses/llm-zoomcamp/project.md after a generated-file-only URL edit;
• moving Docs main is now f6c8527d349fceec6e8e89cc255c6d484ffbf22f / tree 2e856b9a818e0c3123b9efaf3879c2b999c04899, four commits ahead and not adopted by this issue.

Existing templates correctly omit repository/edit chrome, and their absence is the required public behavior. Existing code/tests are evidence inputs only: #41 has no engineer handoff, independent tester report, PM acceptance, focused commit, green release, or source-to-projection proof.

Delivery phases

1. Offline source/parser and parity foundation

• #292 parses a caller-supplied immutable checkout, classifies the complete source and compatibility scope, and produces a deterministic fail-closed report without changing runtime or checked output.

2. Source selection and direct-sync ingestion

After #292, PM must re-census its complete findings and groom bounded children for:

• choosing and evidencing one immutable Docs source commit/tree rather than following moving main;
• resolving every source/projection mismatch without hand-editing generated output;
• wiring the accepted parser into #38’s source-owned direct-sync runner, ownership partition, partial-recovery, status, Studio/admin, and management-only edit/provenance interfaces.

This phase depends on #38’s owner-approved exhaustive source rollout and public-authority decisions plus its applicable accepted children. The current staged ContentRelease candidate/activation/rollback architecture is not reintroduced.

3. Public compatibility, rendering, and search cutover

A separately groomed cutover child must:

• account for every approved Docs public HTML/asset/JSON/XML path and alias with #35; no unresolved row may pass;
• preserve server-rendered navigation, breadcrumbs, heading/fragments, safe Markdown/Liquid-relative links, images, canonical/SEO behavior, no-JS meaning, keyboard/focus/reflow, and error/empty states;
• prove public provenance/edit chrome is absent while authorized management surfaces expose the exact source target;
• switch public readers only after source/direct-sync parity is complete and the last-known-safe boundary is demonstrated;
• integrate section-level search only through #44’s accepted cross-source interface.

Parent acceptance criteria

• Every source blob has one reviewed adoption or exclusion disposition, every adopted page/asset is reproducible from the accepted immutable source, and no checked generated byte is hand-authored.
• Every approved Docs URL, slash/case/Unicode/percent spelling, redirect/retirement exception, fragment, asset, canonical, metadata, and machine contract passes the exact compatibility manifest with no unexplained row.
• Parent/grand-parent navigation, order, breadcrumbs, explicit permalinks, heading anchors/collisions, links, tables, code, callouts, Mermaid, images, raw HTML sanitization, and section search pass representative and corpus-wide validation.
• Ambiguous/broken hierarchy, unsafe metadata/HTML/URL/media, traversal/symlink/resource excess, partial sync, stale provenance, failed search build, and source drift fail safely while prior public-safe content remains available.
• Public pages contain no repository/edit/provenance controls or metadata. Authorized management surfaces retain exact moving-branch edit targets and immutable audit provenance with Studio/admin parity.
• Desktop/mobile and JavaScript-on/off browser evidence covers home, nested navigation/breadcrumbs, deep heading links, rich content, safe denials/404, keyboard/focus/reflow, and inspected screenshots.
• Engineer, independent tester, PM, focused commits, no-ff integration, push CI, deployment, readiness, exact live identity, and post-deploy route/search checks all pass for every child. #41 closes only after the final public/search cutover is live and healthy.

Non-goals

No public edit/source link; no public repository/revision/path/checksum/modification metadata; no Docs authoring in Studio; no URL redesign; no title-based parent guessing; no client-only content/search; no moving-branch runtime fetch; no staged release pointer/preview/activation/rollback graph; no silent approval of the current checked projection, the 29 uncovered paths, or the newer upstream head.

Dependencies

• #35 and historical #37 are closed foundations; #37’s staged lifecycle is not the target architecture.
• #292 is the first unblocked child and has no dependency on #38 or production state.
• Direct sync and management depend on #38’s pending decisions and accepted children.
• Public authority cutover depends on accepted offline/direct-sync parity and complete #35 expectations.
• Unified section search depends on #44.

Start with Spec 03, Spec 02, and the unblocked child #292; review how #35, #38, and #44 define the compatibility, sync, and search boundaries. This epic is done only after bounded children establish reproducible source parity, complete public compatibility, safe rendering and search, management-only provenance, and a healthy final cutover.