(CODUX-117) Integrate docs embedding into setup backend

[numnx]

🧩 Task: Integrate docs embedding into setup backend

Automated task PR opened by Code UX for T02.

📋 Summary

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

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:50:58 UTC
Finished	2026-07-08 17:59:21 UTC
Duration	8m 24s

📊 Token Usage

Metric	Value
Input tokens	128,543
Cached input tokens	4,459,648
Output tokens	16,996
Total tokens	4,605,187
Invocations	1
Tool calls	85
Active time	8m 2s

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

✅ 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
Make `docs` a first-class Project Setup Agent option that automatically embeds discovered repository documentation when requested.

## Scope
- `src/contracts/project-management-types.ts`
- `src/services/project-setup-service.ts`
- `src/services/project-setup-prompt-builder.ts`
- `src/app/dependency-factory/dashboard-factory.ts`
- `src/mcp/management/project-actions.ts`
- `src/contracts/internal-management-types.ts`
- `src/contracts/mcp-tool-definitions.ts`
- `tests/backend/services/project-setup-service.test.ts`
- `tests/backend/mcp/management-project-actions.test.ts`
- Consumes `ProjectDocsAutoEmbedService` from `src/services/project-docs-auto-embed-service.ts`

## Implementation Requirements
1. Extend `ProjectSetupOptions` with `docs: boolean` and extend `ProjectSetupResult` with `embeddedDocumentIds: string[]` and `embeddedDocumentErrors: Array<{ fileName: string; error: string }>`.
2. Update setup defaults and `normalizeOptions` so `docs` defaults to `false` for backward compatibility unless explicitly requested.
3. Inject `ProjectDocsAutoEmbedService` into `ProjectSetupService` from `dashboard-factory.ts`, using the existing `coreDeps.knowledgeService`; if the service is unavailable and `docs` is requested, report a setup result error entry instead of crashing unrelated artifact generation.
4. When `options.docs` is true, call the docs auto-embed service during setup and merge its document IDs/errors into the setup result while preserving existing created agent, quicksprint, preview script, CI, routing, invocation status, and realtime refresh behavior.
5. Update `buildProjectSetupPrompt` and requested artifact labeling so the setup agent is told that Docs embedding is requested and that Code UX will embed discovered repository documentation into the Knowledge docs library.
6. Fix MCP project setup payload normalization in `handleProjectAction` so both top-level `{ options: { docs: true } }` and documented nested `{ setup: { enabled: true, options: { docs: true } } }` shapes reach `ProjectSetupService.setupProject` with the same `ProjectSetupRequestInput`.
7. Update MCP type definitions and schemas so `manage_projects` setup documents the `docs` option.
8. Add backend tests proving docs embedding runs only when requested, result fields are populated, old setup behavior remains unchanged when `docs` is omitted, and MCP nested setup payloads preserve the docs option.

## Constraints
- Do not change existing setup defaults for `agents`, `quicksprints`, `previewScript`, or `ci`.
- Do not mark setup invocations failed solely because one documentation file cannot be embedded; partial docs failures belong in `embeddedDocumentErrors`.
- Do not write knowledge rows directly from `ProjectSetupService`; route all document creation through `ProjectDocsAutoEmbedService` and `KnowledgeService`.
- Preserve the current provider execution and JSON artifact application flow for non-doc setup artifacts.

## Verification
- Run `pnpm exec vitest run tests/backend/services/project-setup-service.test.ts tests/backend/mcp/management-project-actions.test.ts`.
- Run `pnpm run lint`.
- Success means docs embedding is opt-in, setup results include embedded document metadata, and MCP setup accepts the documented nested payload shape with `docs`.

🌿 Branch Info

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

---

🤖 Generated by Code UX