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:T1d77,
# Repository Navigation for AI Agents

This guide explains how AI agents can efficiently navigate the VoiceAssist repository using machine-readable JSON endpoints.

## Endpoints Overview

| Endpoint                                | Size   | Purpose                        |
| --------------------------------------- | ------ | ------------------------------ |
| `/agent/repo-index.json`                | ~3 MB  | Complete repository structure  |
| `/agent/repo/manifest.json`             | ~50 KB | Curated key files index        |
| `/agent/repo/files/{encoded-path}.json` | Varies | Individual source file content |

## Path Encoding

File paths are encoded for URL safety:

- Forward slashes (`/`) become double underscores (`__`)
- `.json` extension is appended

**Examples:**
| Original Path | Encoded Filename |
| ------------------------------------------ | ---------------------------------------------------- |
| `package.json` | `package.json.json` |
| `services/api-gateway/app/main.py` | `services__api-gateway__app__main.py.json` |
| `apps/web-app/src/app/page.tsx` | `apps__web-app__src__app__page.tsx.json` |
| `docs/ai/AGENT_API_REFERENCE.md` | `docs__ai__AGENT_API_REFERENCE.md.json` |

## Component Categories

Files are categorized by their location in the monorepo:

| Component              | Path Prefix            | Description                  |
| ---------------------- | ---------------------- | ---------------------------- |
| `frontend/web-app`     | `apps/web-app`         | Main user-facing Next.js app |
| `frontend/admin-panel` | `apps/admin-panel`     | Admin dashboard Next.js app  |
| `frontend/docs-site`   | `apps/docs-site`       | Documentation site           |
| `backend/api-gateway`  | `services/api-gateway` | FastAPI backend server       |
| `backend/services`     | `services/*`           | Other backend services       |
| `shared/packages`      | `packages/*`           | Shared TypeScript packages   |
| `infra`                | `infrastructure/*`     | Infrastructure configs       |
| `infra/k8s`            | `k8s/*`, `ha-dr/*`     | Kubernetes configs           |
| `docs`                 | `docs/*`               | Documentation markdown       |
| `testing`              | `tests/*`, `e2e/*`     | Test files                   |
| `tooling`              | `scripts/*`            | Build and utility scripts    |
| `root`                 | (no prefix)            | Root-level config files      |

## Navigation Patterns

### Pattern 1: Top-Down Discovery

Start with the manifest to understand project structure:

```bash
# 1. Get overview stats
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '{
  files: .stats.total_files,
  dirs: .stats.total_dirs,
  size_mb: (.stats.total_size_bytes / 1048576 | floor),
  languages: .stats.by_language,
  components: .stats.by_component
}'

# 2. List key entry points from manifest
curl https://assistdocs.asimo.io/agent/repo/manifest.json | jq '[.files[] | select(.path | endswith("main.py") or endswith("page.tsx"))]'
```

### Pattern 2: Component-Focused Search

When working on a specific component:

```bash
# Find all files in web-app
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.component == "frontend/web-app" and .type == "file")]'

# Find React components
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.component == "frontend/web-app" and (.path | test("components/")))]'
```

### Pattern 3: Keyword Search

Find files by name pattern:

```bash
# Find files with "voice" in path
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | test("voice"; "i"))]'

# Find hook files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | test("use[A-Z].*\\.ts"))]'
```

### Pattern 4: Language-Based Exploration

When understanding technology stack:

```bash
# All TypeScript files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.language == "typescript")] | length'

# All Python files in backend
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.language == "python" and (.component | startswith("backend")))]'
```

### Pattern 5: File Content Retrieval

Fetch and analyze source code:

```bash
# Get file content
curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__main.py.json | jq '{
  path: .path,
  language: .language,
  lines: .lines,
  content: .content
}'

# Check for specific imports (using content)
curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__main.py.json | jq '.content' | grep -i "from fastapi"
```

## Workflow: Locate a Feature

**Goal**: Find implementation of "voice mode" feature

```bash
# Step 1: Find voice-related docs
curl https://assistdocs.asimo.io/agent/docs.json | jq '[.docs[] | select(.path | test("voice"; "i"))] | map({title, path, ai_summary})'

# Step 2: Find voice-related code files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.type == "file" and (.path | test("voice"; "i")))] | map({path, component, language})'

# Step 3: Categorize by component
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.type == "file" and (.path | test("voice"; "i")))] | group_by(.component) | map({component: .[0].component, count: length})'

# Step 4: Get key implementation file
curl https://assistdocs.asimo.io/agent/repo/files/services__api-gateway__app__api__voice.py.json
```

## Workflow: Audit Docs vs Code

**Goal**: Verify documented API endpoints exist in code

```bash
# Step 1: Get documented API endpoints
curl https://assistdocs.asimo.io/agent/docs.json | jq '[.docs[] | select(.path | test("API_REFERENCE"))]'

# Step 2: Find API route handlers
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | test("services/api-gateway/app/api/.*\\.py$"))]'

# Step 3: Compare documented vs implemented routes
# (Fetch each file and extract route decorators)
```

## Workflow: Understand Package Dependencies

```bash
# Step 1: Get all package.json files
curl https://assistdocs.asimo.io/agent/repo-index.json | jq '[.entries[] | select(.path | endswith("package.json"))]'

# Step 2: Fetch root package.json
curl https://assistdocs.asimo.io/agent/repo/files/package.json.json | jq '.content | fromjson | {dependencies, devDependencies}'

# Step 3: Check pnpm workspace config
curl https://assistdocs.asimo.io/agent/repo/files/pnpm-workspace.yaml.json
```

## Best Practices

### Efficiency

1. **Start with manifest** for common files (faster, smaller payload)
2. **Use repo-index** only when searching across entire codebase
3. **Cache responses** - repo structure doesn't change frequently
4. **Filter server-side** using jq before processing

### Accuracy

1. **Verify paths exist** before fetching file content
2. **Check `last_modified`** to ensure you have current data
3. **Cross-reference docs** when interpreting code

### Limitations

- **File size limit**: Files over 100KB are not exported (error returned)
- **Excluded patterns**: `.env`, secrets, test files, lock files
- **Binary files**: Only text files are included
- **Update frequency**: Regenerated on docs-site build

## Related Documentation

- [Agent API Reference](./AGENT_API_REFERENCE.md) - Complete endpoint documentation
- [Agent Task Index](./AGENT_TASK_INDEX.md) - Common agent tasks
- [Agent Onboarding](./AGENT_ONBOARDING.md) - Getting started guide
6:["slug","ai/REPO_NAVIGATION_FOR_AGENTS","c"]
0:["X7oMT3VrOffzp0qvbeOas",[[["",{"children":["docs",{"children":[["slug","ai/REPO_NAVIGATION_FOR_AGENTS","c"],{"children":["__PAGE__?{\"slug\":[\"ai\",\"REPO_NAVIGATION_FOR_AGENTS\"]}",{}]}]}]},"$undefined","$undefined",true],["",{"children":["docs",{"children":[["slug","ai/REPO_NAVIGATION_FOR_AGENTS","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":"Repository Navigation for AI Agents"}],["$","p",null,{"className":"text-sm text-gray-600 dark:text-gray-400","children":["Sourced from"," ",["$","code",null,{"className":"font-mono text-xs","children":["docs/","ai/REPO_NAVIGATION_FOR_AGENTS.md"]}]]}]]}],["$","a",null,{"href":"https://github.com/mohammednazmy/VoiceAssist/edit/main/docs/ai/REPO_NAVIGATION_FOR_AGENTS.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":"Repository Navigation for AI Agents | Docs | VoiceAssist Docs"}],["$","meta","3",{"name":"description","content":"Patterns and strategies for AI agents to navigate the VoiceAssist repository using machine-readable endpoints."}],["$","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