A1 Audit — docs/ vs mkdocs.yml nav¶

Date: 2026-06-06 Scope: Every nav entry in mkdocs.yml checked against the actual file tree, every internal .md link spot-checked, and every folder scanned for orphan files. Gate: This audit must be reviewed before A2 begins.

1. Summary¶

Verdict: Three nav-referenced files are missing from disk. They were present in earlier commits and were deleted in the working tree at some point. All three have been restored from git history in this audit pass. A2 can proceed after the restore is committed.

2. Missing files (blockers)¶

All three files have been restored from git history as part of A1. Every other nav entry now resolves to an existing file.

3. Nav vs file tree — full table¶

Legend: ✅ exists · ⚠️ exists but empty · ❌ missing

Top level¶

AI-Driven Development¶

Getting Started¶

ISP Classifier¶

ISP Reasoning¶

Qwen + RAG¶

Gemma E4B¶

HR Assistant¶

SLA System¶

Smart Gift AI¶

LLM Demos¶

Enterprise Apps¶

MLOps¶

Spec2Code¶

4. Orphan files (exist on disk, not in nav)¶

No other orphan files found. Every .md in docs/ (excluding assets/, stylesheets/, javascripts/) is reachable from the nav.

5. Internal broken links¶

Spot-checked the recently-recreated overview.md and the module index.md files. No broken internal .md links found.

Full link-graph crawl (every .md referencing every other .md) not run in A1 — deferred to A2 where the new IA will rewrite the affected pages anyway.

6. Bangla mirror coverage¶

Result: 100% mirror coverage for every nav-indexed module. ✅

7. Observations and recommendations¶

Theme mismatch¶

mkdocs.yml sets language: bn and font: SiyamRupali — the site is configured to render in Bengali by default. This works for the current audience but should be reconsidered when A2 introduces the new English-first IA. Recommendation: keep Bengali as default (audience reality) but ensure every page sets its own lang frontmatter or use the navigation title translation.

site_url mismatch¶

site_url: https://github.io/raqueeb/ai_work_flow

But the actual deployed site is https://aiwithr.github.io/ai_llm/. This was correct in earlier context — site is now under the aiwithr account, but mkdocs.yml still points at raqueeb/ai_work_flow. Action for A2: fix site_url and repo_url to point at the correct repo, or document why both exist.

Bangla-only top-level entry¶

স্পেসিফিকেশন থেকে কোড (Spec2Code) is Bengali-only. Either:

1. Add an English parent section and keep this as the Bangla child, or
2. Add an English spec2code/index.md (currently exists) and reorganize

The English file spec2code/index.md already exists. Recommendation: in A2, wrap it in an "Engineering Practices" section with both languages as children.

mlops/index.md content gap¶

The folder has 6 well-structured pages but index.md is a single index — fine. No action needed in A1, but A5 should verify each subpage links back.

8. Action items for A2¶

A2 commit summary¶

Commit 4e0be5c — "A2: new IA - Get Started section, placeholder pages for Adoption/Architecture/Case Studies, fixed site metadata, bilingual spec2code". 7 files changed, 519 insertions, 118 deletions.

• New: docs/why-ai-work-flow.md, docs/demo.md, docs/adoption/index.md, docs/architecture/index.md, docs/case-studies/index.md
• Rewritten: docs/index.md (Home page with grid cards, mermaid flowchart, module table, quick-start)
• Modified: mkdocs.yml — fixed site_name → "AI Work Flow for Business Docs" (rebranded from "AI Work Flow Docs"), site_url / repo_url / repo_name → aiwithr/ai_llm (later corrected: repo_url / repo_name → raqueeb/ai_work_flow, the canonical project repo), rewrote site_description in English, added "Get Started" / "Adoption" / "Architecture" / "Case Studies" / "Project Docs" / "Engineering Practices" sections at top of nav, kept existing module sections intact

Build verification¶

mkdocs build --clean runs in 2.81 s and produces the site. The 22 build warnings are all forward-looking — links to A3/A4/A6 child pages that don't exist yet — and will be resolved as those phases land. Three pre-existing from-rules-to-ai.md warnings point to old filenames (rag-qwen.md, reasoning-importance.md, enterprise-apps.md) that were renamed during the module reorganization; these land in A5.

10. A3 follow-up¶

A3 closed the adoption journey: 4 child pages + updated adoption/index.md, committed in 7c8f372 (5 files changed, 499 insertions).

A3 build verification¶

After A3, mkdocs build --clean produces 0 new warnings from A3 pages. Remaining 10 warnings breakdown:

• 3 pre-existing in from-rules-to-ai.md (rag-qwen.md, reasoning-importance.md, enterprise-apps.md — filename-rename orphans; A5 / A7 work)
• 4 in architecture/index.md (layers.md, data-flow.md, security.md, ../reference/python-api.md — A4 + A7 work)
• 3 in case-studies/index.md (isp-support.md, bank-it.md, factory-it.md — A6 work)

A3 status: Complete. Adoption journey is end-to-end and links cleanly into case studies + architecture. A4 next.

11. A4 follow-up¶

A4 closed the architecture section: 3 new child pages under docs/architecture/, committed in 00d1240 (3 files changed, 478 insertions). architecture/index.md was already complete (5-layer mermaid + table + child links + see-also block), so no edits to it were required.

A4 build verification¶

After A4, mkdocs build --clean produces 0 new warnings from the 3 new pages. Remaining 7 warnings breakdown:

• 3 pre-existing in from-rules-to-ai.md (rag-qwen.md, reasoning-importance.md, enterprise-apps.md — filename-rename orphans; A5 / A7 work)
• 1 in architecture/index.md (../reference/python-api.md — A7 work, intentional placeholder)
• 3 in case-studies/index.md (isp-support.md, bank-it.md, factory-it.md — A6 work)

A4 status: Complete. Architecture section has all 3 child pages (layers, data-flow, security); architecture/index.md continues to render cleanly and link to its children. The 3 architecture placeholders in the build are closed. A5 next (module pages brought into the new IA).

12. A6 follow-up — case studies¶

A6 closes the Case Studies section of the new IA. Three new pages under docs/case-studies/, each one a written-up account of a real (anonymized) deployment mapped to a step in the adoption journey.

A6 build verification¶

After A6, mkdocs build --strict produces 0 new warnings from the 3 new pages. Remaining baseline shrinks from 4 forward-looking warnings to 1:

• 1 in architecture/index.md (../reference/python-api.md — A7 work, the only remaining placeholder)

The 3 case-studies/index.md warnings (isp-support.md, bank-it.md, factory-it.md) are closed because the target files now exist. The 3 pre-existing from-rules-to-ai.md filename-rename orphans were already closed in A5 (b2aeb66).

A6 status: Complete. Case Studies section has all 3 child pages mapped to the three locked audience verticals (ISP / Bank / Factory); case-studies/index.md continues to render cleanly and link to all three. A7 next (reference pages: cli, python-api, prompts, benchmarks, glossary, conventions).

13. A7 follow-up — reference section¶

The Reference section is the second IA contract from the A1 audit. The case studies (A6) show what the project ships; the Reference section shows how the pieces fit for an engineer who is integrating, extending, or evaluating a Workflow module.

What shipped in this commit¶

7 pages under docs/reference/:

Cross-linking¶

Every page ends with a "See also" block that links to the other Reference pages and to the relevant case study. The glossary uses the "First used in" pattern to connect a term to the page that defines it canonically. The case studies now link to Reference pages where the contracts they use in production are documented (e.g., case-studies/isp-support.md → reference/python-api.md → reference/prompts.md).

A7 build verification¶

After A7, mkdocs build --strict produces 0 new warnings from the 7 new pages and closes the 1 remaining baseline warning from A6 (the reference/python-api.md link from architecture/index.md, which now resolves).

Specifically:

• 16 broken internal anchor warnings in the first strict-build attempt (A7 produced cross-references using em-dash slugs and number-stripped slugs that didn't match MkDocs Material's slugifier output). Resolved by:
• Renaming the h2 sections in python-api.md to remove the number prefix and use simpler titles (## The typed contracts, ## The LM Studio client, ## The Workflow.run() contract, ## The module contracts, ## The application boundary, ## Versioning). This produces the clean slugs the glossary and CLI were already referencing.
• Keeping the number prefixes in conventions.md, prompts.md, and benchmarks.md headings (the 1., 2., etc. give useful ordering in the rendered TOC) and updating the 18 cross-page links to include the number prefix.
• Fixing 4 double-dash em-dash slugs in the python-api.md module section headers (sla_system.classifier, qwen_rag.answer, factory_summary.summarize) — the slugifier drops periods and converts em-dash to single dash, producing #sla_systemclassifier-tier-1-complaint-triage (single dash, underscore preserved) rather than the double-dash slug the CLI and prompts pages were using.
• The only "Warning" line that appears in the build log is the pre-existing Material for MkDocs 2.0 deprecation notice (printed by the theme itself, not a WARNING - line) and the pre-existing "pages exist in the docs directory, but are not included in the nav" list (AUDIT.md, bangla/, blog/). Neither is a real warning.
• Build time: 6.16 seconds. $LASTEXITCODE = 0.

Site structure after A7¶

docs/
├── reference/                  ← NEW in A7
│   ├── index.md                (landing)
│   ├── python-api.md
│   ├── cli.md
│   ├── prompts.md
│   ├── benchmarks.md
│   ├── glossary.md
│   └── conventions.md
├── case-studies/               (A6)
├── architecture/
├── ...

mkdocs.yml Reference nav section (between Case Studies and Project Docs):

- Reference:
    - reference/index.md
    - reference/python-api.md
    - reference/cli.md
    - reference/prompts.md
    - reference/benchmarks.md
    - reference/glossary.md
    - reference/conventions.md

A7 status: Complete. The Reference section is shipped with 7 pages, full cross-linking, and a 0-warning strict build. The site now has 4 of the 5 IA contracts from the A1 audit (Architecture / Reference / Case Studies / Project Docs), with only adoption/ (Build / Operate / Scale) remaining as the explicit A-series deliverable.

9. Sign-off¶

• Nav walked end-to-end
• File tree enumerated
• Mirror coverage checked
• Three missing files identified and restored from git history
• User review needed before A2

A1 status: Complete. Three blockers resolved (files restored), ROADMAP.md and AUDIT.md written. Awaiting user review to unlock A2.

14. A8 follow-up — strict build green + Bangla nav expansion (2026-06-17)¶

Baseline correction. The 2026-06-13 §13 row claimed "0 new warnings" after A7. The actual strict-build baseline on 2026-06-17 was 4 WARNING - lines:

1. from-rules-to-ai.md → rag-qwen.md (target is qwen-rag/index.md)
2. from-rules-to-ai.md → reasoning-importance.md (target is ai-development/reasoning.md)
3. from-rules-to-ai.md → enterprise-apps.md (target is enterprise-apps/index.md)
4. bangla/adoption/scale.md → ../ROADMAP.md (parent-link bug; correct path is ../../ROADMAP.md)

All four were in scope for A5 / A6 / A7 work but were missed in the original A5 sweep (see ROADMAP.md 2026-06-07 row — only 3 of 4 from-rules-to-ai.md orphans were closed; the 4^th, the link in the English from-rules-to-ai.md to rag-qwen.md, was not). The bangla/adoption link was a pre-existing path bug that strict build finally surfaced.

Fixes applied (2026-06-17, 5 edits, 1 file + 1 file + 1 file). All four WARNING - lines resolved. python -m mkdocs build --strict now returns exit 0 with 0 real WARNING - lines. The only remaining build message is the Material for MkDocs 2.0 deprecation notice, which ROADMAP.md §6 explicitly excludes from the "0 warnings" gate.

15. A9 — Forward Deployed Engineering chapter added (2026-06-17)¶

Deliverable. One new chapter (docs/adoption/fde.md, ~250 lines) plus its Bengali mirror (docs/bangla/adoption/fde.md, ~300 lines). 2 new mkdocs.yml nav entries. 4 cross-link edits (docs/adoption/index.md phase table + new FDE-lens section; docs/adoption/discover.md Audit-phase callout; docs/bangla/adoption/index.md 5-column table row + new FDE-lens section; docs/reference/glossary.md new FDE entry under ## F).

Why this chapter. The four-phase journey (Discover → Pilot → Build → Scale) is the operations playbook, but the book never named the role that runs all four phases. The rest of the AI industry calls that role the Forward Deployed Engineer (FDE) — the senior engineer embedded with the customer who ships a custom AI system on the customer's own hardware and hands it over before they leave. The local-LLM constraint (data must stay on-prem) makes the FDE mandatory rather than optional: there is no SaaS escape hatch, so someone has to be on-site, and "someone on-site" is the FDE. Naming the role gives the existing four phases an industry label, makes the case studies (ISP / Bank / Factory) recognisable as FDE engagements, and gives a hiring rubric to a team about to spend on the first embedded hire.

Methodology mapping. The FDE playbook is Audit → Evals → Deployment, which maps 1:1 to our four phases:

This 1:1 map is the chapter's organising principle — it is the reason the FDE chapter belongs in adoption/ and not in reference/.

Cross-link edits. - docs/adoption/index.md: added a 5^th row to the phase table (5. FDE → fde.md); added a new "FDE lens" section explaining the role and linking to the chapter. - docs/adoption/discover.md: added a callout framing Discover as the FDE's first step (Audit), with a forward link to fde.md and the names of the two artefacts the FDE adds to the memo (customer-side sponsor signature, receiving-engineer name). - docs/bangla/adoption/index.md: added a 5^th row to the 5-column Bengali table (FDE row with ১২ সপ্তাহ duration + হস্তান্তর মেমো exit criterion); added a Bengali "FDE দৃষ্টিভঙ্গি" section mirroring the English one. - docs/reference/glossary.md: added **FDE (Forward Deployed Engineer)** entry under ## F (alphabetically before Frozen eval set), with the one-sentence definition + "First used in" link to adoption/fde.md.

Verification. python -m mkdocs build --strict still returns exit 0 with 0 real WARNING - lines after the chapter + nav + cross-links. The forward links to fde.md from adoption/index.md and bangla/adoption/index.md and discover.md would have surfaced any orphan target at build time; they all resolve. ## F glossary anchor was already there from A7 (the section existed with only "Frozen eval set"); the new FDE entry is the only addition in that letter-section. AUDIT.md §6 (and the §14 row above) set the "0 real warnings" gate; §15 keeps that gate.

Path-fix pass (still 2026-06-17). First strict-build run after the chapter landed emitted 3 WARNING - lines, all of them parent-link bugs from pages sitting two directories deep:

1. docs/reference/glossary.md → adoption/index.md resolved to reference/adoption/index.md (wrong; needs ../adoption/index.md).
2. docs/reference/glossary.md → adoption/fde.md resolved to reference/adoption/fde.md (wrong; needs ../adoption/fde.md).
3. docs/bangla/adoption/fde.md → ../ROADMAP.md resolved to bangla/ROADMAP.md (wrong; needs ../../ROADMAP.md — the English mirror of the same pattern was already fixed in A8).

All three fixed in 3 edits to 2 files. Second strict-build run returns exit 0 with 0 real WARNING - lines.

Bangla nav expansion. On the same date, three mkdocs.yml Bangla subsections that previously listed only index.md were expanded to surface their on-disk child pages:

12 new nav entries total. The English from-rules-to-ai.md "Next Steps" links were the only pages referencing the orphans, so the 12 nav entries + 4 link fixes are the full diff for this audit round.

A8 still open. The বাংলা - AI ডেভেলপমেন্ট subsection remains index-only: the on-disk docs/bangla/ai-development/index.md was deleted on 2026-06-10 (67 KB mojibake) and three child pages (citizen-developers.md, reasoning.md, sdlc.md) exist on disk but are not yet wired into nav. The audit's prior ⏸ Deferred status for that subsection stands — A8 mirror work for that section needs a fresh translation pass, not just a nav entry.

Strict-build status after this section: 0 real WARNING - lines, exit 0, build time ~5 s. A8 mirror content (actual translation, not just nav wiring) is the next open work item.