(CODUX-117) Create docs auto-embed service

[numnx]

🧩 Task: Create docs auto-embed service

Automated task PR opened by Code UX for T01.

📋 Summary

Sprint: Sprint 188 · Auto Embed docs Setup Agent · Task: T01

Add a Project Setup Agent option to auto-embed relevant repository documentation into the project Knowledge docs library, expose it in dashboard and MCP setup flows, and document the behavior.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.5

⏱️ Timing

Started	2026-07-08 17:39:51 UTC
Finished	2026-07-08 17:47:14 UTC
Duration	7m 23s

📊 Token Usage

Metric	Value
Input tokens	106,877
Cached input tokens	1,332,352
Output tokens	15,427
Total tokens	1,454,656
Invocations	2
Tool calls	41
Active time	6m 48s

Included usage estimate (subscription/local login): $1.66

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Create a reusable service that safely finds documentation-like files in a project repository and submits them to the existing Knowledge docs ingestion pipeline.

## Scope
- Create `src/services/project-docs-auto-embed-service.ts`
- Create `tests/backend/services/project-docs-auto-embed-service.test.ts`
- Use existing `KnowledgeService.ingestDocument` from `src/services/knowledge-service.ts`
- Use existing knowledge document source type `repo_path` from `src/contracts/knowledge-types.ts`

## Implementation Requirements
1. Export a `ProjectDocsAutoEmbedService` with an async method such as `embedProjectDocs(projectId: string, projectBaseDir: string): Promise<ProjectDocsAutoEmbedResult>`.
2. Discover repository documentation files from the project root using deterministic rules: include root `README*`, `CHANGELOG*`, `CONTRIBUTING*`, assistant instruction markdown such as `AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, and files under `docs/` with doc-oriented extensions such as `.md`, `.mdx`, `.txt`, `.rst`, `.adoc`, `.html`, and `.htm`.
3. Exclude generated, dependency, VCS, cache, and output directories such as `.git`, `node_modules`, `dist`, `build`, `coverage`, `.cache`, `.turbo`, `.next`, `.output`, and `.code-ux/embeddings`; skip symlinks and prevent traversal outside `projectBaseDir` by resolving real paths.
4. Add bounded traversal limits for file count and total bytes, collect per-file errors without failing the whole setup run, and return document IDs plus `{ fileName, error }` entries for skipped or failed files.
5. Ingest each selected file through `KnowledgeService.ingestDocument(projectId, { title: relativePath, sourceType: "repo_path", sourceRef: relativePath, buffer })` so existing dedupe, chunking, embedding, and status behavior remains centralized.
6. Cover discovery ordering, directory exclusion, outside-root protection, partial failure handling, and ingestion payload shape with focused Vitest tests.

## Constraints
- Do not duplicate chunking, embedding, or content-hash logic from `KnowledgeService` or `KnowledgeRepository`.
- Do not require a loaded embedding model inside the discovery service; preserve current `KnowledgeService.ingestDocument` behavior for embedding status.
- Keep traversal deterministic and stable across platforms by normalizing returned source refs to POSIX-style relative paths.
- Do not ingest source code broadly; this task is for documentation-oriented files only.

## Verification
- Run `pnpm exec vitest run tests/backend/services/project-docs-auto-embed-service.test.ts`.
- Run `pnpm run lint`.
- Success means supported docs are ingested with `sourceType: "repo_path"`, excluded directories are ignored, partial failures are reported, and TypeScript passes.

🌿 Branch Info

Base: feature/CODUX-188-auto-embed-docs-setup-agent
Head: task/feature-codux-188-auto-embed-docs-setup-agent-t01-codex-mrcd4xxd

---

🤖 Generated by Code UX