Deliver source-backed FAQ pages, stable anchors, and exact JSON feeds

Parent epic: #4
Offline adapter child: #293
Future database-reader cutover: #38 / #276
Search integration: #44

Normative authority:

• 03 — source ownership and public provenance boundary
• 03 — FAQ adapter
• 02 — FAQ URL, fragment, and JSON compatibility
• 10 — verification strategy

Product outcome

Keep DataTalks.Club’s FAQ source-backed and reproducible while preserving the established anonymous contracts:

• /faq/ course catalogue;
• /faq/<course>.html details and stable ten-character question fragments;
• /faq/json/courses.json with {course,course_name,path,questions_count};
• /faq/json/<course>.json with {id,course,section,question,answer};
• source course/section/question ordering, raw Markdown answers, literal Jinja/Liquid/dbt-looking text, safe referenced images, and stable links.

GitHub provenance is not public product copy. Per specification 03, public FAQ pages and feeds must not render repository names, revisions, checksums, source paths, source-status diagnostics, or “Edit on GitHub” links. The source edit target is preserved only for future authenticated Studio/audit workflows.

Current-state census — 2026-08-30

The checked website projection at origin/main@face8e4808d65afbf0374d1ced7a88079950d663 is content/faq_projection.json SHA-256 7b6e5723b2ab0cf453254c10fb06a08175ca2bee5b9c65d98cc0534acfe8f209. It pins DataTalksClub/faq@c8da1deea9e24945922702994de101dd90a5380a, tree f880b4b63cdd1b213bd1303d8874e4ce02e63965, and contains:

• 6 courses, 70 populated sections, and 1,401 globally unique questions;
• per-course counts in accepted public order: 404, 93, 471, 139, 41, 253;
• 101 image declarations resolving to 99 unique referenced assets;
• management-only source_path/edit_url values inside the checked build projection; and
• no public edit link in the current FAQ templates or five-/four-field JSON responses.

Current FAQ source main is green at commit 3a170c98ad6af394408595f697ce6624ffab155f, tree 6b00fa01f1bc9fee4147b4f6e30f685a429f98c8, source CI run 33236963075. Its selected FAQ corpus contains 6 course metadata files, 74 declared/70 populated sections, 1,406 questions, 101 image declarations/99 unique references, and 136 image files. Relative to the checked pin it adds five LLM questions and changes two answers; it changes no course/section metadata or image.

The old planning count of 1,395 and the former requirement to render public FAQ edit links are superseded. The exact baseline/current census and compatibility exceptions are specified in #293.

Delivery decomposition

A. Offline pinned parser and feed projection — #293

#293 is the only engineer-ready lane from this refresh. It implements a bounded, deterministic, network-free content_sync adapter over a caller-supplied immutable checkout, proves the checked baseline and current green target, preserves management-only provenance internally, and produces exact feed projections. It performs no activation and changes no public reader or checked projection.

This slice is independent of #38 because it adds no direct-sync schema, ingress, job, lock, database mutation, public-authority decision, or provider access.

B. Checked projection adoption and public regression — separately groom after #293 acceptance

After #293 is accepted, PM must groom a focused child that selects an accepted immutable FAQ pin, regenerates the checked projection/assets only through the accepted adapter/evidence path, and verifies page/feed/fragment/render compatibility with independent desktop/mobile screenshots. Do not infer that pin or apply mutable source main directly.

This baked-reader update does not require database direct-sync activation. It must still run on the then-current repaired website base and must not mix unrelated source families.

C. Database-backed reader cutover — #38 / #276

#276 owns any later switch from the checked projection to direct-sync rows, including authority, freshness, observation, and compatibility-window evidence. #42 does not invent a second activation/rollback model. #44 remains downstream for FAQ search.

Parent acceptance criteria

• #293 is accepted and merged with deterministic immutable-source, schema, safety, asset, feed-parity, provenance-denial, and failure evidence.
• A separately groomed adoption child pins one immutable green FAQ source revision and regenerates the checked FAQ projection/assets reproducibly with a reviewed census/delta.
• /faq/ lists every adopted course in accepted order and exposes only canonical public navigation.
• Every adopted /faq/<course>.html preserves section/question order, safe Markdown rendering, literal template-looking source text, stable ten-character fragments, canonical metadata, FAQ structured data, and referenced images.
• /faq/json/courses.json and each /faq/json/<course>.json preserve exact paths, status, application/json content type, field sets, value types, raw answers, record order, and unknown-course 404 behavior.
• Public FAQ HTML, feeds, structured data, search/sitemap output, and anonymous responses contain no edit URL, repository, revision, tree, checksum, source path, or source diagnostic.
• Duplicate/invalid IDs, invalid course/section membership, unsafe YAML/paths/markup/URLs, missing/conflicting images, invalid UTF-8 structures, and bounded resource overruns fail safely without changing the prior checked projection or public response.
• Independent tester evidence covers focused Django plus graph-selected suites and all graph-required desktop/mobile screenshots; PM accepts navigation, deep-link/focus behavior, literal snippets, long/code-rich answers, images, empty/error states, and provenance denial.

Browser scenarios for the future public adoption child

1. Open /faq/ at desktop and mobile; verify course order/counts, canonical navigation, and no source/edit disclosure.
2. Open representative long, code-rich, Unicode, image-bearing, and literal-Jinja questions at /faq/<course>.html#<10-char-id> with JavaScript on/off as selected by the graph; verify the correct disclosure target, fragment/focus behavior, wrapped code, stable permalink, safe links/images, and screenshots.
3. Request both JSON feed kinds and an unknown course; verify exact payload fields/order/types/content type and 404 behavior, with no provenance fields.
4. Exercise an invalid candidate and confirm the previously checked FAQ pages/feeds remain byte-identical.

Dependencies

• #35 and #37 are closed historical prerequisites, not active blockers.
• #293 is the active implementation prerequisite for any new checked FAQ projection.
• #38/#276 are not dependencies of the offline adapter or continued baked FAQ reader; they are required only for a database-backed reader cutover.
• #44 is downstream and does not block page/feed parity.

This parent is an epic, not a broad engineer dispatch. Child commits use Refs #42; close #42 only after the adapter and public checked-projection lifecycle above are accepted. A future direct-sync cutover may follow without reopening this page/feed compatibility contract.

Non-goals

No public edit/source links, source repository writes, mutable-head activation, arbitrary template execution, feed schema enhancement, anchor regeneration, Studio authoring, search implementation, webhook/reconciliation, provider credentials, database direct sync, reader cutover, or production/provider operation in this parent lane.

Start by reading the linked specifications and the decomposition for #293; inspect content/faq_projection.json and the stated source and projection census. Run the focused Django and graph-selected suites described in the acceptance criteria. This parent is done only after the adapter, a separately groomed projection-adoption child, and the listed page, feed, safety, and provenance evidence are accepted.