2:I[7012,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],"MarkdownRenderer"] 4:I[9856,["4765","static/chunks/4765-f5afdf8061f456f3.js","9856","static/chunks/9856-3b185291364d9bef.js","6687","static/chunks/app/docs/%5B...slug%5D/page-e07536548216bee4.js"],""] 5:I[4126,[],""] 7:I[9630,[],""] 8:I[4278,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"HeadingProvider"] 9:I[1476,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Header"] a:I[3167,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"Sidebar"] b:I[7409,["9856","static/chunks/9856-3b185291364d9bef.js","8172","static/chunks/8172-b3a2d6fe4ae10d40.js","3185","static/chunks/app/layout-2814fa5d15b84fe4.js"],"PageFrame"] 3:T189f, # TODO: Documentation Enhancement Phase 2 > **For AI Agents**: This document contains actionable tasks to continue the documentation enhancement work. Phase 1 (AI summaries at 100%, code-excerpts.json creation) is complete. ## Context **Completed in Phase 1:** - AI summary coverage: 100% (255/255 docs) - Code excerpts: 2,034 excerpts extracted to `/agent/code-excerpts.json` - Health metrics enhanced with `code_excerpts` section - CODEOWNERS updated for new scripts - CI workflow updated to generate code excerpts **Related Files:** - `/apps/docs-site/scripts/generate-code-excerpts.js` - Extracts code from codebase - `/apps/docs-site/public/agent/code-excerpts.json` - Generated excerpts - `/scripts/generate-all-agent-json.js` - Main agent JSON generator - `/apps/docs-site/public/agent/health.json` - Coverage metrics --- ## Task 1: code_refs Frontmatter ### Goal Link documentation pages to relevant code excerpts using a `code_refs` frontmatter field, enabling AI agents to quickly find the actual implementation code for any doc. ### Implementation Steps 1. **Define the `code_refs` schema** in frontmatter: ```yaml --- title: "Voice Pipeline Architecture" code_refs: - id: "services/api-gateway/app/services/voice_pipeline_service.py:VoicePipelineService" description: "Main voice pipeline service class" - id: "services/api-gateway/app/services/tts_service.py:TTSService" description: "Text-to-speech service" --- ``` 2. **Create a mapping script** (`apps/docs-site/scripts/map-code-refs.js`): - Read all docs with their categories/tags - Read `code-excerpts.json` - Use heuristics to suggest relevant code excerpts: - Match doc title keywords to code excerpt names - Match doc category to code category (e.g., `api` docs → `api` excerpts) - Match `relatedServices` frontmatter to service class names - Output suggestions for manual review or auto-apply 3. **Update `docs-summary.json`** to include `code_refs`: - Modify `generateDocsSummary()` in `generate-all-agent-json.js` - Include `code_refs` array in each doc entry 4. **Create validation** (`apps/docs-site/scripts/validate-code-refs.js`): - Verify all `code_refs` IDs exist in `code-excerpts.json` - Warn about broken references - Suggest missing refs based on content analysis ### Files to Modify - `apps/docs-site/scripts/generate-agent-json.js` - Parse `code_refs` from frontmatter - `scripts/generate-all-agent-json.js` - Include in `docs-summary.json` - `apps/docs-site/scripts/validate-metadata.mjs` - Add `code_refs` validation ### Acceptance Criteria - [ ] At least 50 high-priority docs have `code_refs` frontmatter - [ ] `docs-summary.json` includes `code_refs` for each doc - [ ] Validation script catches broken references - [ ] Health.json reports `code_refs_coverage` percentage --- ## Task 2: Versioning Groundwork ### Goal Enable version-specific documentation and API endpoints to support multiple product versions. ### Implementation Steps 1. **Add version field to frontmatter**: ```yaml --- title: "API Reference" version: "2.0" versions_available: ["1.0", "2.0"] --- ``` 2. **Create versioned directory structure** (optional approach): ``` docs/ ├── v1/ │ └── api/ ├── v2/ │ └── api/ └── current/ -> v2 (symlink) ``` 3. **Update agent endpoints to support version filtering**: - Add `?version=2.0` query param support conceptually - Create `/agent/v2/docs.json` alternate endpoints - Modify `generate-all-agent-json.js`: ```javascript function generateDocs(version = null) { const docs = scanDocsDir(CONFIG.DOCS_DIR); if (version) { return docs.filter((d) => !d.version || d.version === version); } return docs; } ``` 4. **Add version selector component** to docs-site: - File: `apps/docs-site/src/components/VersionSelector.tsx` - Store selected version in localStorage - Filter displayed docs by version 5. **Update index.json** with versioned endpoints: ```json { "endpoints": { "docs_v2": { "path": "/agent/v2/docs.json", "description": "Version 2.0 documentation index" } }, "available_versions": ["1.0", "2.0"], "current_version": "2.0" } ``` ### Files to Create - `apps/docs-site/src/components/VersionSelector.tsx` - `apps/docs-site/public/agent/v2/` directory structure ### Files to Modify - `scripts/generate-all-agent-json.js` - Add version filtering - `apps/docs-site/scripts/generate-agent-json.js` - Parse version frontmatter - `apps/docs-site/public/agent/index.json` - Add version metadata ### Acceptance Criteria - [ ] Docs can have `version` frontmatter field - [ ] Agent endpoints can filter by version - [ ] `index.json` lists available versions - [ ] Version selector UI component exists (even if not fully integrated) --- ## Quick Reference for AI Agents ### Key Commands ```bash # Regenerate all agent JSON files node scripts/generate-all-agent-json.js --all # Generate code excerpts from codebase node apps/docs-site/scripts/generate-code-excerpts.js # Generate AI summaries for docs missing them node apps/docs-site/scripts/generate-ai-summaries.js --dry-run # Validate documentation metadata pnpm --filter docs-site validate:metadata ``` ### Key Endpoints to Update | File | Purpose | | -------------------------- | ------------------------------------ | | `/agent/docs.json` | Add `code_refs` and `version` fields | | `/agent/docs-summary.json` | Include `code_refs` array | | `/agent/health.json` | Add `code_refs_coverage` metric | | `/agent/index.json` | Add version metadata | ### Testing Changes 1. Run generators locally 2. Check output JSON files for correctness 3. Run `pnpm --filter docs-site build` to verify site builds 4. Verify health.json metrics are accurate --- ## Priority Order 1. **Task 1 (code_refs)** - High value for AI agents navigating docs↔code 2. **Task 2 (versioning)** - Important for multi-version product support Estimated effort: 2-4 hours each task for an AI agent with full context. 6:["slug","planning/TODO_DOCS_ENHANCEMENT_PHASE2","c"] 0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","planning/TODO_DOCS_ENHANCEMENT_PHASE2","c"],{"children":["__PAGE__?{\"slug\":[\"planning\",\"TODO_DOCS_ENHANCEMENT_PHASE2\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","planning/TODO_DOCS_ENHANCEMENT_PHASE2","c"],{"children":["__PAGE__",{},[["$L1",["$","div",null,{"children":[["$","div",null,{"className":"mb-6 flex items-center justify-between gap-4","children":[["$","div",null,{"children":[["$","p",null,{"className":"text-sm text-gray-500 dark:text-gray-400","children":"Docs / Raw"}],["$","h1",null,{"className":"text-3xl font-bold text-gray-900 dark:text-white","children":"TODO: Documentation Enhancement Phase 2"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","planning/TODO_DOCS_ENHANCEMENT_PHASE2.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/planning/TODO_DOCS_ENHANCEMENT_PHASE2.md","target":"_blank","rel":"noreferrer","className":"inline-flex items-center gap-2 rounded-md border border-gray-200 dark:border-gray-700 px-3 py-1.5 text-sm text-gray-700 dark:text-gray-200 hover:border-primary-500 dark:hover:border-primary-400 hover:text-primary-700 dark:hover:text-primary-300","children":"Edit on GitHub"}]]}],["$","div",null,{"className":"rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 p-6","children":["$","$L2",null,{"content":"$3"}]}],["$","div",null,{"className":"mt-6 flex flex-wrap gap-2 text-sm","children":[["$","$L4",null,{"href":"/reference/all-docs","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"← All documentation"}],["$","$L4",null,{"href":"/","className":"inline-flex items-center gap-1 rounded-md bg-gray-100 px-3 py-1 text-gray-700 hover:bg-gray-200 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700","children":"Home"}]]}]]}],null],null],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children","$6","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[null,["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children","docs","children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","notFoundStyles":"$undefined"}]],null]},[[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/css/7f586cdbbaa33ff7.css","precedence":"next","crossOrigin":"$undefined"}]],["$","html",null,{"lang":"en","className":"h-full","children":["$","body",null,{"className":"__className_f367f3 h-full bg-white dark:bg-gray-900","children":[["$","a",null,{"href":"#main-content","className":"skip-to-content","children":"Skip to main content"}],["$","$L8",null,{"children":[["$","$L9",null,{}],["$","$La",null,{}],["$","main",null,{"id":"main-content","className":"lg:pl-64","role":"main","aria-label":"Documentation content","children":["$","$Lb",null,{"children":["$","$L5",null,{"parallelRouterKey":"children","segmentPath":["children"],"error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L7",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":"404"}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],"notFoundStyles":[]}]}]}]]}]]}]}]],null],null],["$Lc",null]]]] c:[["$","meta","0",{"name":"viewport","content":"width=device-width, initial-scale=1"}],["$","meta","1",{"charSet":"utf-8"}],["$","title","2",{"children":"TODO: Documentation Enhancement Phase 2 | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Documentation page for TODO: Documentation Enhancement Phase 2 sourced from the docs directory."}],["$","meta","4",{"name":"keywords","content":"VoiceAssist,documentation,medical AI,voice assistant,healthcare,HIPAA,API"}],["$","meta","5",{"name":"robots","content":"index, follow"}],["$","meta","6",{"name":"googlebot","content":"index, follow"}],["$","link","7",{"rel":"canonical","href":"https://assistdocs.asimo.io"}],["$","meta","8",{"property":"og:title","content":"VoiceAssist Documentation"}],["$","meta","9",{"property":"og:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","10",{"property":"og:url","content":"https://assistdocs.asimo.io"}],["$","meta","11",{"property":"og:site_name","content":"VoiceAssist Docs"}],["$","meta","12",{"property":"og:type","content":"website"}],["$","meta","13",{"name":"twitter:card","content":"summary"}],["$","meta","14",{"name":"twitter:title","content":"VoiceAssist Documentation"}],["$","meta","15",{"name":"twitter:description","content":"Comprehensive documentation for VoiceAssist - Enterprise Medical AI Assistant"}],["$","meta","16",{"name":"next-size-adjust"}]] 1:null