diff --git a/dashboard/src/v2/ProjectsPage.tsx b/dashboard/src/v2/ProjectsPage.tsx
index f73abfc13c..1d2829d09c 100644
--- a/dashboard/src/v2/ProjectsPage.tsx
+++ b/dashboard/src/v2/ProjectsPage.tsx
@@ -3,6 +3,7 @@ import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/ho
 import gsap from "gsap";
 import { useNavigate } from "@tanstack/react-router";
 import {
+    BookOpen,
     Bot,
     Check,
     Circle,
@@ -18,7 +19,7 @@ import {
     Sparkles,
     Trash2,
 } from "lucide-preact";
-import type { Source, SourceStatus } from "./types.js";
+import type { ProjectSetupOptions, Source, SourceStatus } from "./types.js";
 import { AddProjectModal, type AddProjectModalSubmission, type SourceType as AddProjectModalSourceType } from "./components/ui/AddProjectModal.js";
 import { buildProjectCreationSettingsOverride } from "../lib/settings-updaters.js";
 import { DEFAULT_DASHBOARD_SETTINGS } from "../lib/settings.js";
@@ -37,6 +38,14 @@ import { buildProjectCardViewModel } from "./lib/project-card-view-model.js";
 
 const EMBER_HEX = '#FFB800';
 
+const createDefaultSetupOptions = (): ProjectSetupOptions => ({
+    agents: true,
+    quicksprints: true,
+    previewScript: true,
+    ci: true,
+    techstack: true,
+    docs: false,
+});
 
 type Filter = 'All' | 'Running' | 'Idle' | 'Failed';
 
@@ -453,13 +462,7 @@ export const ProjectsPage: FunctionComponent = () => {
     const [runningSetupProjectIds, setRunningSetupProjectIds] = useState<Set<string>>(() => new Set());
     const [setupInvocationByProjectId, setSetupInvocationByProjectId] = useState<Record<string, string>>({});
     const [setupError, setSetupError] = useState<string | null>(null);
-    const [setupOptions, setSetupOptions] = useState({
-        agents: true,
-        quicksprints: true,
-        previewScript: true,
-        ci: true,
-        techstack: true,
-    });
+    const [setupOptions, setSetupOptions] = useState<ProjectSetupOptions>(() => createDefaultSetupOptions());
     const [activeFilter, setActiveFilter] = useState<Filter>('All');
     const {
         projects: sources,
@@ -542,13 +545,7 @@ export const ProjectsPage: FunctionComponent = () => {
     const launchProjectSetup = (
         projectId: string,
         projectName: string,
-        options: {
-            agents: boolean;
-            quicksprints: boolean;
-            previewScript: boolean;
-            ci: boolean;
-            techstack: boolean;
-        },
+        options: ProjectSetupOptions,
     ) => {
         setRunningSetupProjectIds(prev => new Set(prev).add(projectId));
         addToast({
@@ -810,7 +807,7 @@ export const ProjectsPage: FunctionComponent = () => {
                                         onDelete={() => { void deleteProject(source.id); }}
                                         onSetup={() => {
                                             setSetupProjectId(source.id);
-                                            setSetupOptions({ agents: true, quicksprints: true, previewScript: true, ci: true, techstack: true });
+                                            setSetupOptions(createDefaultSetupOptions());
                                             setSetupError(null);
                                         }}
                                         onOpenInvocation={() => {
@@ -872,21 +869,29 @@ export const ProjectsPage: FunctionComponent = () => {
                                     { key: "previewScript", label: "Preview Script", description: "Container startup." },
                                     { key: "ci", label: "CI", description: "Basic checks." },
                                     { key: "techstack", label: "Techstack", description: "Detect and assign from manifests." },
+                                    { key: "docs", label: "Docs", description: "Embed repository docs into Knowledge docs.", icon: BookOpen },
                                 ] as const).map((option) => (
                                     <button
                                         key={option.key}
                                         type="button"
                                         onClick={() => setSetupOptions(prev => ({ ...prev, [option.key]: !prev[option.key] }))}
                                         disabled={isActiveSetupRunning}
-                                        className={`rounded-2xl border p-4 text-left transition-all disabled:cursor-not-allowed disabled:opacity-60 ${
+                                        className={`flex min-w-0 items-start gap-3 rounded-2xl border p-4 text-left transition-all disabled:cursor-not-allowed disabled:opacity-60 ${
                                             setupOptions[option.key]
                                                 ? "border-ember-500/35 bg-ember-500/[0.08] text-slate-900 dark:text-white"
                                                 : "border-black/[0.06] bg-black/[0.025] text-slate-500 dark:border-white/[0.08] dark:bg-white/[0.035] dark:text-slate-400"
                                         }`}
                                         aria-pressed={setupOptions[option.key]}
                                     >
-                                        <span className="block text-xs font-black uppercase tracking-[0.14em]">{option.label}</span>
-                                        <span className="mt-1 block text-xs font-medium opacity-75">{option.description}</span>
+                                        {"icon" in option ? (
+                                            <span className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-xl ${setupOptions[option.key] ? "bg-ember-500 text-void-900" : "bg-black/[0.04] text-slate-400 dark:bg-white/[0.06]"}`}>
+                                                <option.icon className="h-4 w-4" aria-hidden="true" />
+                                            </span>
+                                        ) : null}
+                                        <span className="min-w-0 flex-1">
+                                            <span className="block text-xs font-black uppercase tracking-[0.14em]">{option.label}</span>
+                                            <span className="mt-1 block text-xs font-medium opacity-75">{option.description}</span>
+                                        </span>
                                     </button>
                                 ))}
                             </div>
diff --git a/dashboard/src/v2/components/ui/AddProjectModal.tsx b/dashboard/src/v2/components/ui/AddProjectModal.tsx
index b1f8a76351..d95561dde3 100644
--- a/dashboard/src/v2/components/ui/AddProjectModal.tsx
+++ b/dashboard/src/v2/components/ui/AddProjectModal.tsx
@@ -1,25 +1,17 @@
 import type { FunctionComponent } from "preact";
 import { useRef, useState, useMemo } from "preact/hooks";
 import gsap from "gsap";
-import { AlertCircle, Bot, Check, ChevronUp, Cloud, FolderOpen, GitBranch, FolderInput, Globe, Home, Info, Layers3, Link2, Loader2, Lock, PlaySquare, Plus, RefreshCw, ShieldCheck, Sparkles, Workflow, X } from "lucide-preact";
+import { AlertCircle, BookOpen, Bot, Check, ChevronUp, Cloud, FolderOpen, GitBranch, FolderInput, Globe, Home, Info, Layers3, Link2, Loader2, Lock, PlaySquare, Plus, RefreshCw, ShieldCheck, Sparkles, Workflow, X } from "lucide-preact";
 import { FormError } from "../forms/FormError.js";
 import { Modal } from "./Modal.js";
 import { ActionFeedbackRegion } from "./ActionFeedbackRegion.js";
 import { fetchLocalDirectories } from "../../lib/project-api.js";
-import type { LocalDirectoryBrowserResponse } from "../../types.js";
+import type { LocalDirectoryBrowserResponse, ProjectSetupOptions } from "../../types.js";
 import type { ApplicationKind } from "../../../types.js";
 import { DEFAULT_DASHBOARD_SETTINGS } from "../../../lib/settings.js";
 
 export type SourceType = 'local' | 'git' | 'new_project';
 
-type ProjectSetupOptions = {
-    agents: boolean;
-    quicksprints: boolean;
-    previewScript: boolean;
-    ci: boolean;
-    techstack: boolean;
-};
-
 type ExistingProjectSubmission = {
     name: string;
     type: 'local' | 'git';
@@ -102,12 +94,13 @@ export const AddProjectModal: FunctionComponent<AddProjectModalProps> = ({ onClo
     const [newIsPrivate, setNewIsPrivate] = useState(true);
     const [initializeProject, setInitializeProject] = useState(true);
     const [showSetupOptions, setShowSetupOptions] = useState(false);
-    const [setupOptions, setSetupOptions] = useState({
+    const [setupOptions, setSetupOptions] = useState<ProjectSetupOptions>({
         agents: true,
         quicksprints: true,
         previewScript: false,
         ci: true,
         techstack: true,
+        docs: false,
     });
     const [submitError, setSubmitError] = useState<string | null>(null);
     const [activeDirectoryPickerTarget, setActiveDirectoryPickerTarget] = useState<DirectoryPickerTarget | null>(null);
@@ -379,6 +372,7 @@ export const AddProjectModal: FunctionComponent<AddProjectModalProps> = ({ onClo
         { key: "previewScript", label: "Preview Script", description: "Container startup script for browser previews.", icon: PlaySquare },
         { key: "ci", label: "CI", description: "Basic GitHub/GitLab error-checking pipelines.", icon: ShieldCheck },
         { key: "techstack", label: "Techstack", description: "Detect and assign a project stack from manifests.", icon: Layers3 },
+        { key: "docs", label: "Docs", description: "Embed repository docs into Knowledge docs.", icon: BookOpen },
     ] as const;
 
     return (
@@ -659,7 +653,7 @@ export const AddProjectModal: FunctionComponent<AddProjectModalProps> = ({ onClo
                                                 </div>
                                                 <button
                                                     type="button"
-                                                    onClick={() => setSetupOptions({ agents: true, quicksprints: true, previewScript: true, ci: true, techstack: true })}
+                                                    onClick={() => setSetupOptions({ agents: true, quicksprints: true, previewScript: true, ci: true, techstack: true, docs: true })}
                                                     className="rounded-xl bg-white px-3 py-2 text-[10px] font-black uppercase tracking-[0.14em] text-slate-600 shadow-sm transition-colors hover:text-slate-900 dark:bg-white/[0.08] dark:text-slate-300 dark:hover:text-white"
                                                 >
                                                     All
diff --git a/dashboard/src/v2/types.ts b/dashboard/src/v2/types.ts
index d5cb6dacc5..a5f916e3f1 100644
--- a/dashboard/src/v2/types.ts
+++ b/dashboard/src/v2/types.ts
@@ -82,6 +82,7 @@ import type {
   PlanningOverrides,
   PlanSprintOptions,
   ProjectCollectionResponse,
+  ProjectSetupOptions,
   ProjectSetupRequestInput,
   ProjectSetupResult,
   ProjectSetupStartResult,
@@ -317,6 +318,7 @@ export type {
   PostListenReplyInput,
   PullInboxInput,
   ProjectCollectionResponse,
+  ProjectSetupOptions,
   ProjectSetupRequestInput,
   ProjectSetupResult,
   ProjectSetupStartResult,
diff --git a/docs-web/content/docs/developer-management-actions.mdx b/docs-web/content/docs/developer-management-actions.mdx
index 68bfc2dd47..c690a45c03 100644
--- a/docs-web/content/docs/developer-management-actions.mdx
+++ b/docs-web/content/docs/developer-management-actions.mdx
@@ -31,7 +31,7 @@ Domain for project CRUD and selection.
 | `create` | – | `CreateProjectInput` | Create a new project. |
 | `update` | – | `projectId`, `UpdateProjectInput` | Update a project. |
 | `select` | – | `projectId \| null` | Set the active project. |
-| `setup` | – | `projectId`, optional `setup` | Run the Project Setup Agent to generate agents, templates, and guidance. |
+| `setup` | – | `projectId`, optional `setup` or top-level `options` | Run the Project Setup Agent to generate agents, templates, guidance, and optional docs embedding (`options.docs`). |
 | `delete` | ✅ | `projectId` | Delete a project (+ approval). |
 
 `CreateProjectInput` includes: `name`, `repositoryPath`, optional `defaultBranch`, `featureBranchPrefix`, `description`, `githubMode`.
diff --git a/docs-web/content/docs/developer-mcp-tools.mdx b/docs-web/content/docs/developer-mcp-tools.mdx
index d7c3d6f4fa..f959e0f4dd 100644
--- a/docs-web/content/docs/developer-mcp-tools.mdx
+++ b/docs-web/content/docs/developer-mcp-tools.mdx
@@ -78,6 +78,8 @@ Every tool requires `runtimeRoles: ["project_manager"]` and is enabled by defaul
 | `manage_chat_providers` | `list_provider_definitions`, `list_connections`, `get_connection`, `create_connection`, `update_connection`, `delete_connection`, `list_channel_bindings`, `create_channel_binding`, `update_channel_binding`, `delete_channel_binding`, `list_outbound_deliveries` |
 | `manage_telemetry` | `get_project_stats_snapshot`, `get_project_execution_snapshot`, `list_execution_invocations`, `list_execution_invocation_messages`, `list_sprint_runs`, `list_task_dispatches` |
 
+For `manage_projects` setup, clients may send setup options either as `setup.options` or as top-level `options`. `options.docs: true` is opt-in and embeds discovered repository documentation into the Knowledge docs library.
+
 For the full per-action payloads and return shapes, see [Management actions](/docs/developer-management-actions).
 
 ## `scheduler_code_ux`
diff --git a/docs-web/content/docs/user-dashboard-projects.mdx b/docs-web/content/docs/user-dashboard-projects.mdx
index 3b7899d688..dbe8ac43d6 100644
--- a/docs-web/content/docs/user-dashboard-projects.mdx
+++ b/docs-web/content/docs/user-dashboard-projects.mdx
@@ -28,7 +28,7 @@ The form collects:
 | Repository URL | Yes for Git URL imports | Remote repository to clone and track. |
 | Git URL slug | Yes for new remote apps | Repository slug for backend remote initialization. It auto-fills from the project name until edited. |
 | Init mode | Yes for new projects | `Local Repo` creates a local repository; `Remote Repo` initializes a remote repository and clone. |
-| Setup scope | Optional for imports | Runs the Project Setup Agent for imported local or Git projects. Setup can generate agents, quicksprints, preview startup, CI, and a detected techstack from repository evidence. New app initialization hides setup scope controls. |
+| Setup scope | Optional for imports | Runs the Project Setup Agent for imported local or Git projects. Setup can generate agents, quicksprints, preview startup, CI, a detected techstack, and opt-in docs embedding from repository evidence. New app initialization hides setup scope controls. |
 
 On save, Code UX:
 
@@ -39,6 +39,8 @@ On save, Code UX:
 
 For imported projects, setup techstack detection inspects dependency manifests, especially `package.json`, plus lockfiles and framework config files. When the detection is valid, Code UX adds the stack to the system catalog if needed and writes the project selection to `techstack.selectedTechstackId`. Invalid or empty detections are ignored without blocking other selected setup artifacts, so imported projects are not classified until evidence or an operator assigns them.
 
+Docs setup is opt-in from the dashboard setup scope or setup request payloads. When `docs` is true, Code UX discovers repository documentation and embeds it through the Knowledge docs library, returning embedded document IDs plus per-file errors without failing the rest of setup for a single document failure.
+
 ## Selecting the active project
 
 Most other dashboard pages operate on a *single active project*. The active project is selectable from:
diff --git a/docs-web/developer/management-actions.md b/docs-web/developer/management-actions.md
index 0d597cc0bd..70a3228269 100644
--- a/docs-web/developer/management-actions.md
+++ b/docs-web/developer/management-actions.md
@@ -31,7 +31,7 @@ Domain for project CRUD and selection.
 | `create` | – | `CreateProjectInput` | Create a new project. |
 | `update` | – | `projectId`, `UpdateProjectInput` | Update a project. |
 | `select` | – | `projectId \| null` | Set the active project. |
-| `setup` | – | `projectId`, optional `setup` | Run the Project Setup Agent to generate agents, templates, and guidance. |
+| `setup` | – | `projectId`, optional `setup` or top-level `options` | Run the Project Setup Agent to generate agents, templates, guidance, and optional docs embedding (`options.docs`). |
 | `delete` | ✅ | `projectId` | Delete a project (+ approval). |
 
 `CreateProjectInput` includes: `name`, `repositoryPath`, optional `defaultBranch`, `featureBranchPrefix`, `description`, `githubMode`.
diff --git a/docs-web/developer/mcp-tools.md b/docs-web/developer/mcp-tools.md
index 51454ac2fc..27fc157a25 100644
--- a/docs-web/developer/mcp-tools.md
+++ b/docs-web/developer/mcp-tools.md
@@ -78,6 +78,8 @@ Every tool requires `runtimeRoles: ["project_manager"]` and is enabled by defaul
 | `manage_chat_providers` | `list_provider_definitions`, `list_connections`, `get_connection`, `create_connection`, `update_connection`, `delete_connection`, `list_channel_bindings`, `create_channel_binding`, `update_channel_binding`, `delete_channel_binding`, `list_outbound_deliveries` |
 | `manage_telemetry` | `get_project_stats_snapshot`, `get_project_execution_snapshot`, `list_execution_invocations`, `list_execution_invocation_messages`, `list_sprint_runs`, `list_task_dispatches` |
 
+For `manage_projects` setup, clients may send setup options either as `setup.options` or as top-level `options`. `options.docs: true` is opt-in and embeds discovered repository documentation into the Knowledge docs library.
+
 For the full per-action payloads and return shapes, see [Management actions](./management-actions.md).
 
 ## `scheduler_code_ux`
diff --git a/docs-web/user/dashboard/projects.md b/docs-web/user/dashboard/projects.md
index 847a28abb2..1aefa8587b 100644
--- a/docs-web/user/dashboard/projects.md
+++ b/docs-web/user/dashboard/projects.md
@@ -28,7 +28,7 @@ The form collects:
 | Repository URL | Yes for Git URL imports | Remote repository to clone and track. |
 | Git URL slug | Yes for new remote apps | Repository slug for backend remote initialization. It auto-fills from the project name until edited. |
 | Init mode | Yes for new projects | `Local Repo` creates a local repository; `Remote Repo` initializes a remote repository and clone. |
-| Setup scope | Optional for imports | Runs the Project Setup Agent for imported local or Git projects. Setup can generate agents, quicksprints, preview startup, CI, and a detected techstack from repository evidence. New app initialization hides setup scope controls. |
+| Setup scope | Optional for imports | Runs the Project Setup Agent for imported local or Git projects. Setup can generate agents, quicksprints, preview startup, CI, a detected techstack, and opt-in docs embedding from repository evidence. New app initialization hides setup scope controls. |
 
 On save, Code UX:
 
@@ -39,6 +39,8 @@ On save, Code UX:
 
 For imported projects, setup techstack detection inspects dependency manifests, especially `package.json`, plus lockfiles and framework config files. When the detection is valid, Code UX adds the stack to the system catalog if needed and writes the project selection to `techstack.selectedTechstackId`. Invalid or empty detections are ignored without blocking other selected setup artifacts, so imported projects are not classified until evidence or an operator assigns them.
 
+Docs setup is opt-in from the dashboard setup scope or setup request payloads. When `docs` is true, Code UX discovers repository documentation and embeds it through the Knowledge docs library, returning embedded document IDs plus per-file errors without failing the rest of setup for a single document failure.
+
 ## Selecting the active project
 
 Most other dashboard pages operate on a *single active project*. The active project is selectable from:
diff --git a/docs/architecture/agent-knowledge-base.md b/docs/architecture/agent-knowledge-base.md
index c0af2f97e2..c4d68c7aec 100644
--- a/docs/architecture/agent-knowledge-base.md
+++ b/docs/architecture/agent-knowledge-base.md
@@ -16,6 +16,8 @@ Supported ingest paths:
 
 Repo-path ingestion resolves `path` inside the selected project's `baseDir`, rejects traversal outside the project directory, and skips common generated or dependency directories when walking a directory.
 
+`ProjectDocsAutoEmbedService` provides a reusable setup-time path for automatically finding documentation-like repository files and passing them through `KnowledgeService.ingestDocument` as `sourceType: "repo_path"` documents. It only selects root documentation files (`README*`, `CHANGELOG*`, `CONTRIBUTING*`, assistant instruction markdown) plus supported documentation extensions under `docs/`, skips generated/dependency/cache/VCS directories and symlinks, enforces file-count and byte limits, and reports per-file errors without duplicating chunking, embedding, or content-hash logic.
+
 Project imports copy extracted document text into the target project as `sourceType: "project"` documents. The target project embeds the copied documents with the active embedding model and still deduplicates by content hash inside that project.
 
 ## Memory Auto-Capture
diff --git a/docs/dashboard/dashboard-guide.md b/docs/dashboard/dashboard-guide.md
index b2996d853d..e58d0dbea9 100644
--- a/docs/dashboard/dashboard-guide.md
+++ b/docs/dashboard/dashboard-guide.md
@@ -40,7 +40,8 @@ Project management:
   - Creates a project (`local` or `git`)
   - May include `setup.enabled: true` with setup options to run the Project Setup Agent immediately after creation
 - `POST /api/projects/:projectId/setup`
-  - Runs the Project Setup Agent for an existing project and applies selected setup artifacts (`agents`, `quicksprints`, `previewScript`, `ci`)
+  - Runs the Project Setup Agent for an existing project and applies selected setup artifacts (`agents`, `quicksprints`, `previewScript`, `ci`, `techstack`, and opt-in `docs`)
+  - When `docs` is enabled, discovered repository documentation is ingested into the project's Knowledge docs library; individual file failures are returned as setup diagnostics without failing the whole setup run
   - With `background: true`, returns `202` plus `invocationId` immediately so the dashboard can track the run in the invocation rail while setup continues server-side
 - `PATCH /api/projects/:projectId`
   - Updates project metadata
@@ -341,8 +342,8 @@ Legacy runtime:
 - The Projects page `Add Project` placeholder card uses the same full-height card footprint and internal padding as project cards, and the add dialog fields use rounded field surfaces with amber focus states instead of bare underline inputs; the dialog also constrains itself to the viewport on shorter screens
 - The `Add Project` dialog now has a wider desktop layout, keeps a stable Git-form-height floor while switching source types, and exposes the inline directory browser on both local project paths and optional Git clone destination paths, with home, refresh, parent-directory navigation, child-directory traversal, and an explicit use-current-folder action
 - The `Add Project` dialog now also includes a `New Project` source type. That branch keeps creation inside the same modal, preselects `Local Repo` or `Remote Repo` init modes, shows provider and visibility toggles for remote initialization, and skips the Project Setup Agent controls entirely.
-- The `Add Project` dialog preselects Project Setup Agent initialization. When enabled, creation advances to a setup scope step where operators choose Agents, Quicksprint Templates, Preview Container Script, and CI before the backend creates repository-specific artifacts.
-- Existing project cards expose a Project Setup Agent action that opens the same setup scope for later initialization or regeneration. See [Project Initialization](./project-initialization.md).
+- The `Add Project` dialog preselects Project Setup Agent initialization. When enabled for imported local or Git projects, creation advances to a setup scope step where operators choose Agents, Quicksprint Templates, Preview Container Script, CI, Techstack, and opt-in Docs embedding before the backend creates repository-specific artifacts. Docs sends discovered repository documentation through the same Knowledge ingestion, dedupe, and embedding behavior used by the Knowledge page.
+- Existing project cards expose a Project Setup Agent action that opens the same setup scope for later initialization or regeneration, including the opt-in Docs option for adding repository documentation to Knowledge. See [Project Initialization](./project-initialization.md).
 - Project setup runs display immediate toast feedback, an `Initializing` project-card state, and direct `Open invocation` actions while the background setup invocation is running and after it finishes.
 - Git URL projects are cloned into a local checkout before the project record is created. When the optional clone directory is left empty, Code UX uses `~/.code-ux/projects/<repo-name>` so Docker workspaces always seed from a real repository root instead of a relative placeholder path.
 - Project selector and project cards now refresh over websocket when the project collection or selected project changes
diff --git a/docs/dashboard/project-initialization.md b/docs/dashboard/project-initialization.md
index 28ef0378f8..521b9221ab 100644
--- a/docs/dashboard/project-initialization.md
+++ b/docs/dashboard/project-initialization.md
@@ -17,13 +17,14 @@ Project Initialization runs a repository-specific setup pass through the `Projec
 - New remote init clones into the selected clone directory, or `~/.code-ux/projects` when the field is blank, and stores the project base directory as the single checkout root `~/.code-ux/projects/<repo-name>`.
 - Existing projects expose a `Setup Project` action from the project card agent button.
 
-Imported-project setup lets the operator choose which artifacts to create:
+Imported-project setup lets the operator choose which generated artifacts to create. The dashboard keeps Docs disabled by default; selecting it embeds discovered repository documentation into Knowledge docs. Backend and MCP setup requests can also explicitly enable docs embedding:
 
 - `Agents`
 - `Quicksprints`
 - `Preview Script`
 - `CI`
 - `Techstack`
+- `Docs` (opt-in)
 
 ## Backend Flow
 
@@ -32,7 +33,7 @@ The dashboard calls:
 - `POST /api/projects/:projectId/setup`
 - `POST /api/projects/:projectId/setup` with `background: true`
 
-Project creation can also include:
+Project creation can also include the same setup request shape:
 
 ```json
 {
@@ -43,7 +44,8 @@ Project creation can also include:
       "quicksprints": true,
       "previewScript": true,
       "ci": true,
-      "techstack": true
+      "techstack": true,
+      "docs": true
     }
   }
 }
@@ -57,6 +59,27 @@ Project setup base-agent context is sourced from the bundled Code UX defaults in
 
 The dashboard uses background mode for user-triggered setup. The endpoint returns `202` with the created `invocationId` immediately, then the setup run continues server-side. The project card shows an `Initializing` state with the invocation short id, and toast notifications link directly to `/chat?mode=invocations&invocation=<id>` for live tracking and completion review.
 
+Foreground setup responses include the applied artifact summary:
+
+```json
+{
+  "ok": true,
+  "projectId": "project-id",
+  "invocationId": "invocation-id",
+  "agentId": "project-setup-agent-id",
+  "summary": "Setup summary",
+  "createdAgentIds": ["agent-id"],
+  "createdQuicksprintTemplateIds": ["template-id"],
+  "writtenFiles": [".code-ux/browser/start-preview.sh"],
+  "embeddedDocumentIds": ["knowledge-document-id"],
+  "embeddedDocumentErrors": [
+    { "fileName": "docs/broken.md", "error": "Failed to ingest file" }
+  ]
+}
+```
+
+`embeddedDocumentIds` lists Knowledge document records created from repository documentation during this setup run. `embeddedDocumentErrors` lists per-file discovery or ingestion failures. These errors are partial-failure diagnostics: provider-generated setup artifacts can still be applied and the setup response can still be successful when one documentation file cannot be embedded.
+
 ## Generated Artifacts
 
 When selected, setup can create or update:
@@ -67,6 +90,7 @@ When selected, setup can create or update:
 - `.github/workflows/code-ux-basic-checks.yml`
 - `.gitlab-ci.yml`
 - a detected system techstack catalog entry selected through the project's `techstack.selectedTechstackId`
+- repository documentation discovered from the checkout and ingested into the project's Knowledge docs library
 
 Agent setup also updates project agent routing:
 
@@ -76,6 +100,8 @@ Agent setup also updates project agent routing:
 
 Techstack setup is non-destructive and best-effort. Imported projects start with `techstack.selectedTechstackId: null`; when the operator enables `Techstack`, the Project Setup Agent inspects dependency evidence, especially `package.json`, lockfiles, workspace manifests, and framework config files. A valid result includes a stack name, description, and detected frameworks/libraries. Code UX adds the detected stack to the system catalog when no matching entry exists, then selects it for the project. Empty, invalid, or contradictory detections are ignored with a warning and do not block other selected setup artifacts.
 
+Docs setup is opt-in and best-effort. When `docs` is enabled, Code UX discovers root documentation and files under `docs/`, then sends each file through the shared Knowledge ingestion pipeline as repository-path docs. The existing Knowledge ingestion path handles dedupe, text extraction, chunking, embedding, and document status updates. Setup reports the document IDs it receives from that path, but it does not guarantee every document has already reached `ready`; status continues to follow the KnowledgeService lifecycle shown on the Knowledge page. Individual documentation failures are reported in `embeddedDocumentErrors` and do not fail the provider-generated setup artifacts.
+
 ## Prompt Requirements
 
 The setup prompt requires the agent to inspect the real repository before proposing artifacts, including assistant instruction files such as `AGENTS.md`, `GEMINI.md`, `Gemini.md`, `CLAUDE.md`, `Claude.md`, project documentation, dependency manifests, package scripts, source layout, existing CI, and preview/runtime configuration. When techstack detection is enabled, `package.json` dependency sections and related manifests are treated as primary evidence.
diff --git a/docs/mcp/tools-and-contracts.md b/docs/mcp/tools-and-contracts.md
index f892264436..e19301c905 100644
--- a/docs/mcp/tools-and-contracts.md
+++ b/docs/mcp/tools-and-contracts.md
@@ -218,7 +218,7 @@ Apply accepts a `bundle` object and optional `scopes` for partial import. Projec
 
 ### Project Setup Action
 
-`manage_projects` supports project setup:
+`manage_projects` supports project setup with the nested setup request shape used by project creation and dashboard setup:
 
 ```json
 {
@@ -230,13 +230,72 @@ Apply accepts a `bundle` object and optional `scopes` for partial import. Projec
       "agents": true,
       "quicksprints": true,
       "previewScript": true,
-      "ci": true
+      "ci": true,
+      "techstack": true,
+      "docs": true
     }
   }
 }
 ```
 
-The action runs the Project Setup Agent and returns the applied artifact summary, including created agent IDs, created quicksprint template IDs, and written project-relative files.
+For the `setup` action, clients may also send the normalized setup request shape directly on the project payload. The same `options.docs` flag is accepted there:
+
+```json
+{
+  "action": "setup",
+  "projectId": "project-id",
+  "options": {
+    "agents": true,
+    "quicksprints": true,
+    "previewScript": true,
+    "ci": true,
+    "techstack": true,
+    "docs": true
+  }
+}
+```
+
+The deprecated `manage_code_ux` envelope delegates `domain: "projects"` setup calls to the same handler, so it accepts the same nested `setup.options` shape:
+
+```json
+{
+  "domain": "projects",
+  "action": "setup",
+  "payload": {
+    "projectId": "project-id",
+    "setup": {
+      "enabled": true,
+      "options": {
+        "agents": true,
+        "quicksprints": true,
+        "previewScript": true,
+        "ci": true,
+        "techstack": true,
+        "docs": true
+      }
+    }
+  }
+}
+```
+
+It also accepts the normalized setup request shape:
+
+```json
+{
+  "domain": "projects",
+  "action": "setup",
+  "payload": {
+    "projectId": "project-id",
+    "options": {
+      "docs": true
+    }
+  }
+}
+```
+
+The action runs the Project Setup Agent and returns the applied artifact summary, including created agent IDs, created quicksprint template IDs, written project-relative files, `embeddedDocumentIds`, and `embeddedDocumentErrors`. `docs` defaults to `false`; when explicitly enabled, Code UX discovers repository documentation and ingests it through the Knowledge docs library without requiring the setup agent to return document contents. The Knowledge pipeline keeps its existing dedupe, extraction, chunking, embedding, and status behavior, so setup does not imply every document is already `ready`.
+
+Docs embedding is best-effort. Individual file failures are reported as `{ "fileName": "...", "error": "..." }` entries in `embeddedDocumentErrors`; they do not fail the entire setup run or roll back provider-generated setup artifacts.
 
 Dashboard calls can add `background: true` to the HTTP setup request. In that mode Code UX returns the created `invocationId` immediately and the invocation rail becomes the live tracking surface while setup continues.
 
diff --git a/src/app/dependency-factory/dashboard-factory.ts b/src/app/dependency-factory/dashboard-factory.ts
index 16bc46682e..3663754e40 100644
--- a/src/app/dependency-factory/dashboard-factory.ts
+++ b/src/app/dependency-factory/dashboard-factory.ts
@@ -7,6 +7,7 @@ import { ExecutionControlService } from "../../services/execution-control-servic
 import { PlanningAgentService } from "../../services/planning-agent-service.js";
 import { QuicksprintService } from "../../services/quicksprint-service.js";
 import { ProjectSetupService } from "../../services/project-setup-service.js";
+import { ProjectDocsAutoEmbedService } from "../../services/project-docs-auto-embed-service.js";
 import { WorkspaceManager } from "../../infrastructure/providers/cli/workspace-manager.js";
 import { formatSprintBranch } from "../../domain/sprint/branch-name-generator.js";
 
@@ -469,6 +470,7 @@ export function createDashboardDependencies(
     quicksprintService,
     providerRunner,
     providerConcurrencyService: coreDeps.providerConcurrencyService,
+    projectDocsAutoEmbedService: new ProjectDocsAutoEmbedService(coreDeps.knowledgeService),
     projectRoot: typeof context.getProjectRoot === "function" ? context.getProjectRoot() : process.cwd(),
     getGithubToken: () => context.getEffectiveGithubToken(),
     logger: logger.child({ component: "project-setup-service" }),
diff --git a/src/contracts/internal-management-types.ts b/src/contracts/internal-management-types.ts
index 1443e475b2..aea3be478a 100644
--- a/src/contracts/internal-management-types.ts
+++ b/src/contracts/internal-management-types.ts
@@ -11,7 +11,7 @@ import type {
   ExternalChannelMetadata,
 } from "./chat-provider-types.js";
 import type { NodeFlowGraph, NodeFlowJsonObject, NodeWidgetSchema } from "./node-flow-types.js";
-import type { CreateProjectInput } from "./project-management-types.js";
+import type { CreateProjectInput, ProjectSetupOptions, ProjectSetupRequestInput } from "./project-management-types.js";
 
 export interface ManagementApproval {
   confirmed: boolean;
@@ -30,6 +30,9 @@ export interface ManageProjectsArgs extends Partial<CreateProjectInput> {
   action: "list" | "get" | "create" | "update" | "select" | "setup" | "delete";
   projectId?: string;
   description?: string;
+  setup?: ProjectSetupRequestInput;
+  options?: Partial<ProjectSetupOptions>;
+  clientRequestId?: string;
   approval?: ManagementApproval;
 }
 
diff --git a/src/contracts/mcp-tool-definitions.ts b/src/contracts/mcp-tool-definitions.ts
index 604def5cd0..12a1a808b3 100644
--- a/src/contracts/mcp-tool-definitions.ts
+++ b/src/contracts/mcp-tool-definitions.ts
@@ -36,7 +36,40 @@ export const TOOL_DEFINITIONS = [
         projectId: { type: "string", description: "Required for get, update, select, setup, delete." },
         name: { type: "string", description: "Required for create. Optional for update." },
         description: { type: "string", description: "Optional for create and update." },
-        setup: { type: "object", additionalProperties: true, description: "Optional setup request with enabled and options flags." },
+        setup: {
+          type: "object",
+          additionalProperties: true,
+          description: "Optional setup request with enabled and options flags. For setup action, options.docs=true embeds discovered repository documentation into Knowledge docs.",
+          properties: {
+            enabled: { type: "boolean", description: "Set to true when requesting setup during project creation." },
+            options: {
+              type: "object",
+              additionalProperties: true,
+              description: "Project setup options. docs defaults to false unless explicitly requested.",
+              properties: {
+                agents: { type: "boolean", description: "Generate repository-specific coding agents." },
+                quicksprints: { type: "boolean", description: "Generate repository-specific quicksprint templates." },
+                previewScript: { type: "boolean", description: "Generate a preview container startup script." },
+                ci: { type: "boolean", description: "Generate basic CI workflow files." },
+                techstack: { type: "boolean", description: "Detect and select the project techstack." },
+                docs: { type: "boolean", description: "Embed discovered repository documentation into the Knowledge docs library. Defaults to false." },
+              },
+            },
+          },
+        },
+        options: {
+          type: "object",
+          additionalProperties: true,
+          description: "Top-level project setup options for action=setup. Supports docs=true to embed discovered repository documentation.",
+          properties: {
+            agents: { type: "boolean", description: "Generate repository-specific coding agents." },
+            quicksprints: { type: "boolean", description: "Generate repository-specific quicksprint templates." },
+            previewScript: { type: "boolean", description: "Generate a preview container startup script." },
+            ci: { type: "boolean", description: "Generate basic CI workflow files." },
+            techstack: { type: "boolean", description: "Detect and select the project techstack." },
+            docs: { type: "boolean", description: "Embed discovered repository documentation into the Knowledge docs library. Defaults to false." },
+          },
+        },
         approval: {
           type: "object",
           properties: {
diff --git a/src/contracts/project-management-types.ts b/src/contracts/project-management-types.ts
index ac16a8a396..c7e94cae56 100644
--- a/src/contracts/project-management-types.ts
+++ b/src/contracts/project-management-types.ts
@@ -394,6 +394,7 @@ export interface ProjectSetupOptions {
   previewScript: boolean;
   ci: boolean;
   techstack: boolean;
+  docs: boolean;
 }
 
 export interface ProjectSetupRequestInput {
@@ -453,6 +454,8 @@ export interface ProjectSetupResult {
   createdAgentIds: string[];
   createdQuicksprintTemplateIds: string[];
   writtenFiles: string[];
+  embeddedDocumentIds: string[];
+  embeddedDocumentErrors: Array<{ fileName: string; error: string }>;
 }
 
 export interface ProjectSetupStartResult {
diff --git a/src/mcp/management/project-actions.ts b/src/mcp/management/project-actions.ts
index 6f6dbaa6ee..f023e7a715 100644
--- a/src/mcp/management/project-actions.ts
+++ b/src/mcp/management/project-actions.ts
@@ -5,6 +5,29 @@ import type { ProjectSetupService } from "../../services/project-setup-service.j
 
 export type ProjectCreateHandler = (input: CreateProjectInput) => Promise<unknown> | unknown;
 
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function normalizeProjectSetupPayload(payload: Record<string, unknown>): ProjectSetupRequestInput {
+  const nestedSetup = asRecord(payload.setup);
+  const source = nestedSetup ?? payload;
+  const options = asRecord(source.options);
+  const normalized: ProjectSetupRequestInput = {};
+  if (typeof source.enabled === "boolean") {
+    normalized.enabled = source.enabled;
+  }
+  if (typeof source.clientRequestId === "string") {
+    normalized.clientRequestId = source.clientRequestId;
+  }
+  if (options) {
+    normalized.options = options as ProjectSetupRequestInput["options"];
+  }
+  return normalized;
+}
+
 export function handleProjectAction(
   action: string,
   payload: Record<string, unknown>,
@@ -45,7 +68,7 @@ export function handleProjectAction(
         throw new Error("Project setup service is not enabled.");
       }
       return projectSetupService
-        .setupProject(projectId, payload as ProjectSetupRequestInput)
+        .setupProject(projectId, normalizeProjectSetupPayload(payload))
         .then((result) => ({ result }));
     }
     case "update": {
diff --git a/src/server/request-parsers.ts b/src/server/request-parsers.ts
index 9319b5c859..a33a82a10c 100644
--- a/src/server/request-parsers.ts
+++ b/src/server/request-parsers.ts
@@ -481,6 +481,7 @@ export function parseProjectSetupRequestInput(body: unknown): ProjectSetupReques
         previewScript: parseOptionalBoolean(optionsInput.previewScript, "setup.options.previewScript"),
         ci: parseOptionalBoolean(optionsInput.ci, "setup.options.ci"),
         techstack: parseOptionalBoolean(optionsInput.techstack, "setup.options.techstack"),
+        docs: parseOptionalBoolean(optionsInput.docs, "setup.options.docs"),
       }
       : undefined,
   };
diff --git a/src/services/project-docs-auto-embed-service.ts b/src/services/project-docs-auto-embed-service.ts
new file mode 100644
index 0000000000..fc32033a40
--- /dev/null
+++ b/src/services/project-docs-auto-embed-service.ts
@@ -0,0 +1,285 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import type { Dirent } from "fs";
+import type { KnowledgeService } from "./knowledge-service.js";
+
+export interface ProjectDocsAutoEmbedError {
+  fileName: string;
+  error: string;
+}
+
+export interface ProjectDocsAutoEmbedResult {
+  documentIds: string[];
+  errors: ProjectDocsAutoEmbedError[];
+}
+
+export interface ProjectDocsAutoEmbedOptions {
+  maxFiles?: number;
+  maxTotalBytes?: number;
+}
+
+interface DiscoveredDocFile {
+  absolutePath: string;
+  relativePath: string;
+}
+
+interface DiscoveryState {
+  realProjectRoot: string;
+  files: Map<string, DiscoveredDocFile>;
+  errors: ProjectDocsAutoEmbedError[];
+  totalBytes: number;
+  truncated: boolean;
+}
+
+const DEFAULT_MAX_FILES = 100;
+const DEFAULT_MAX_TOTAL_BYTES = 25 * 1024 * 1024;
+
+const ROOT_DOC_PREFIXES = ["readme", "changelog", "contributing"];
+const ROOT_ASSISTANT_DOCS = new Set(["agents.md", "gemini.md", "claude.md"]);
+const DOCS_DIRECTORY_NAME = "docs";
+const DOC_EXTENSIONS = new Set([".md", ".mdx", ".txt", ".rst", ".adoc", ".html", ".htm"]);
+
+const EXCLUDED_DIRECTORY_NAMES = new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  ".cache",
+  ".turbo",
+  ".next",
+  ".output",
+]);
+
+/**
+ * Discovers project-authored documentation files and sends them through the shared
+ * knowledge ingestion pipeline. This service intentionally stops at discovery and
+ * file reading; extraction, dedupe, chunking, embedding, and status updates remain
+ * centralized in KnowledgeService.
+ */
+export class ProjectDocsAutoEmbedService {
+  private readonly maxFiles: number;
+  private readonly maxTotalBytes: number;
+
+  constructor(
+    private readonly knowledgeService: Pick<KnowledgeService, "ingestDocument">,
+    options: ProjectDocsAutoEmbedOptions = {},
+  ) {
+    this.maxFiles = Math.max(1, Math.floor(options.maxFiles ?? DEFAULT_MAX_FILES));
+    this.maxTotalBytes = Math.max(1, Math.floor(options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES));
+  }
+
+  async embedProjectDocs(projectId: string, projectBaseDir: string): Promise<ProjectDocsAutoEmbedResult> {
+    const discovered = await this.discoverProjectDocs(projectBaseDir);
+    const documentIds: string[] = [];
+    const errors = [...discovered.errors];
+
+    for (const file of discovered.files) {
+      try {
+        const buffer = await fs.readFile(file.absolutePath);
+        const document = await this.knowledgeService.ingestDocument(projectId, {
+          title: file.relativePath,
+          sourceType: "repo_path",
+          sourceRef: file.relativePath,
+          buffer,
+        });
+        documentIds.push(document.id);
+      } catch (error) {
+        errors.push({ fileName: file.relativePath, error: toErrorMessage(error, "Failed to ingest file") });
+      }
+    }
+
+    return { documentIds, errors };
+  }
+
+  private async discoverProjectDocs(projectBaseDir: string): Promise<{ files: DiscoveredDocFile[]; errors: ProjectDocsAutoEmbedError[] }> {
+    let realProjectRoot: string;
+    try {
+      realProjectRoot = await fs.realpath(path.resolve(projectBaseDir));
+      const stat = await fs.stat(realProjectRoot);
+      if (!stat.isDirectory()) {
+        return { files: [], errors: [{ fileName: ".", error: "Project base path is not a directory" }] };
+      }
+    } catch (error) {
+      return { files: [], errors: [{ fileName: ".", error: toErrorMessage(error, "Project base directory is not readable") }] };
+    }
+
+    const state: DiscoveryState = {
+      realProjectRoot,
+      files: new Map(),
+      errors: [],
+      totalBytes: 0,
+      truncated: false,
+    };
+
+    const rootEntries = await this.readSortedDirectory(realProjectRoot, ".", state.errors);
+    for (const entry of rootEntries) {
+      if (state.truncated) break;
+      const entryPath = path.join(realProjectRoot, entry.name);
+      if (entry.isSymbolicLink()) {
+        if (this.isRootDocFileName(entry.name) || entry.name === DOCS_DIRECTORY_NAME) {
+          state.errors.push({ fileName: entry.name, error: "Skipped symbolic link" });
+        }
+        continue;
+      }
+
+      if (entry.isFile() && this.isRootDocFileName(entry.name)) {
+        await this.addCandidate(state, entryPath, entry.name);
+      } else if (entry.isDirectory() && entry.name === DOCS_DIRECTORY_NAME) {
+        await this.walkDocsDirectory(state, entryPath, DOCS_DIRECTORY_NAME);
+      }
+    }
+
+    return {
+      files: [...state.files.values()].sort((left, right) => compareStable(left.relativePath, right.relativePath)),
+      errors: state.errors,
+    };
+  }
+
+  private async walkDocsDirectory(state: DiscoveryState, directoryPath: string, relativeDirectory: string): Promise<void> {
+    if (state.truncated || this.isExcludedDirectory(relativeDirectory, path.basename(relativeDirectory))) {
+      return;
+    }
+
+    const realDirectoryPath = await this.ensureContainedDirectory(state, directoryPath, relativeDirectory);
+    if (!realDirectoryPath) {
+      return;
+    }
+
+    const entries = await this.readSortedDirectory(realDirectoryPath, relativeDirectory, state.errors);
+    for (const entry of entries) {
+      if (state.truncated) break;
+
+      const childPath = path.join(realDirectoryPath, entry.name);
+      const childRelative = toPosixPath(path.join(relativeDirectory, entry.name));
+
+      if (entry.isSymbolicLink()) {
+        state.errors.push({ fileName: childRelative, error: "Skipped symbolic link" });
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        if (this.isExcludedDirectory(childRelative, entry.name)) {
+          continue;
+        }
+        await this.walkDocsDirectory(state, childPath, childRelative);
+      } else if (entry.isFile() && DOC_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        await this.addCandidate(state, childPath, childRelative);
+      }
+    }
+  }
+
+  private async addCandidate(state: DiscoveryState, absolutePath: string, relativePath: string): Promise<void> {
+    if (state.files.has(relativePath)) {
+      return;
+    }
+    if (state.files.size >= this.maxFiles) {
+      this.markTruncated(state, relativePath, `Documentation discovery truncated at ${this.maxFiles} files`);
+      return;
+    }
+
+    try {
+      const linkStat = await fs.lstat(absolutePath);
+      if (linkStat.isSymbolicLink()) {
+        state.errors.push({ fileName: relativePath, error: "Skipped symbolic link" });
+        return;
+      }
+      const realFilePath = await fs.realpath(absolutePath);
+      if (!isPathInside(state.realProjectRoot, realFilePath)) {
+        state.errors.push({ fileName: relativePath, error: "Skipped path outside project directory" });
+        return;
+      }
+
+      const stat = await fs.stat(realFilePath);
+      if (!stat.isFile()) {
+        return;
+      }
+      if (state.totalBytes + stat.size > this.maxTotalBytes) {
+        this.markTruncated(state, relativePath, `Documentation discovery truncated at ${this.maxTotalBytes} bytes`);
+        return;
+      }
+
+      state.totalBytes += stat.size;
+      state.files.set(relativePath, { absolutePath: realFilePath, relativePath });
+    } catch (error) {
+      state.errors.push({ fileName: relativePath, error: toErrorMessage(error, "Failed to inspect file") });
+    }
+  }
+
+  private async ensureContainedDirectory(state: DiscoveryState, directoryPath: string, relativeDirectory: string): Promise<string | null> {
+    try {
+      const linkStat = await fs.lstat(directoryPath);
+      if (linkStat.isSymbolicLink()) {
+        state.errors.push({ fileName: relativeDirectory, error: "Skipped symbolic link" });
+        return null;
+      }
+      const realDirectoryPath = await fs.realpath(directoryPath);
+      if (!isPathInside(state.realProjectRoot, realDirectoryPath)) {
+        state.errors.push({ fileName: relativeDirectory, error: "Skipped path outside project directory" });
+        return null;
+      }
+      const stat = await fs.stat(realDirectoryPath);
+      if (!stat.isDirectory()) {
+        return null;
+      }
+      return realDirectoryPath;
+    } catch (error) {
+      state.errors.push({ fileName: relativeDirectory, error: toErrorMessage(error, "Failed to inspect directory") });
+      return null;
+    }
+  }
+
+  private async readSortedDirectory(
+    directoryPath: string,
+    relativeDirectory: string,
+    errors: ProjectDocsAutoEmbedError[],
+  ): Promise<Dirent[]> {
+    try {
+      const entries = await fs.readdir(directoryPath, { withFileTypes: true });
+      return entries.sort((left, right) => compareStable(left.name, right.name));
+    } catch (error) {
+      errors.push({ fileName: relativeDirectory, error: toErrorMessage(error, "Failed to read directory") });
+      return [];
+    }
+  }
+
+  private isRootDocFileName(fileName: string): boolean {
+    const lower = fileName.toLowerCase();
+    if (ROOT_ASSISTANT_DOCS.has(lower)) {
+      return true;
+    }
+    return ROOT_DOC_PREFIXES.some((prefix) => lower.startsWith(prefix));
+  }
+
+  private isExcludedDirectory(relativeDirectory: string, directoryName: string): boolean {
+    if (EXCLUDED_DIRECTORY_NAMES.has(directoryName)) {
+      return true;
+    }
+    const normalized = toPosixPath(relativeDirectory);
+    return normalized === ".code-ux/embeddings" || normalized.endsWith("/.code-ux/embeddings");
+  }
+
+  private markTruncated(state: DiscoveryState, fileName: string, error: string): void {
+    if (!state.truncated) {
+      state.errors.push({ fileName, error });
+    }
+    state.truncated = true;
+  }
+}
+
+function isPathInside(basePath: string, targetPath: string): boolean {
+  const relative = path.relative(basePath, targetPath);
+  return relative.length === 0 || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function toPosixPath(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+function compareStable(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function toErrorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error && error.message ? error.message : fallback;
+}
diff --git a/src/services/project-setup-prompt-builder.ts b/src/services/project-setup-prompt-builder.ts
index 6505e8d76e..86798951ac 100644
--- a/src/services/project-setup-prompt-builder.ts
+++ b/src/services/project-setup-prompt-builder.ts
@@ -24,6 +24,7 @@ const requestedArtifacts = (options: ProjectSetupOptions): string[] => {
   if (options.previewScript) artifacts.push("Preview Container Script");
   if (options.ci) artifacts.push("GitHub/GitLab CI");
   if (options.techstack) artifacts.push("Techstack Detection");
+  if (options.docs) artifacts.push("Docs Embedding");
   return artifacts;
 };
 
@@ -264,6 +265,9 @@ export function buildProjectSetupPrompt(args: ProjectSetupPromptArgs): string {
     `Repository root: ${args.project.baseDir}`,
     `Source type: ${args.project.sourceType}`,
     `Requested artifacts: ${selected.length > 0 ? selected.join(", ") : "none"}`,
+    ...(args.options.docs ? [
+      "Docs embedding requested: Code UX will automatically discover repository documentation and embed it into the Knowledge docs library after generated setup artifacts are applied. You should still read repository docs as evidence, but you do not need to return document contents or knowledge rows in the JSON.",
+    ] : []),
     "",
     "## Mandatory Research Scope",
     "- Start by listing the repository root and identifying the package manager, primary language(s), framework(s), app entrypoints, scripts, and test commands.",
@@ -379,5 +383,13 @@ export function buildProjectSetupPrompt(args: ProjectSetupPromptArgs): string {
       "- For CI, produce basic GitHub Actions and/or GitLab CI files only when appropriate for the detected repository. Prefer install, lint if present, typecheck if present, test if present, and build if present.",
       "- CI must use the detected package manager and avoid secret-dependent deployment steps.",
     ] : ["- Set `ci` to an empty array."]),
+    ...(args.options.docs ? [
+      "",
+      "### Docs Embedding Rules",
+      "",
+      "- Do not include embedded documents, document contents, or knowledge-library writes in the JSON output.",
+      "- Code UX will discover root documentation files and files under `docs/`, then embed them into the project's Knowledge docs library after applying this setup response.",
+      "- Use discovered documentation only as evidence for generated agents, quicksprints, preview scripts, CI, and techstack detection.",
+    ] : []),
   ].join("\n");
 }
diff --git a/src/services/project-setup-service.ts b/src/services/project-setup-service.ts
index 031951f573..b99fab9c79 100644
--- a/src/services/project-setup-service.ts
+++ b/src/services/project-setup-service.ts
@@ -5,6 +5,7 @@ import type { DashboardSettings, ProviderId, TechstackCatalogEntrySettings, Tech
 import type {
   ProjectSetupArtifactPayload,
   ProjectSetupOptions,
+  ProjectSetupRequestInput,
   ProjectSetupResult,
   ProjectSetupStartResult,
   ProjectSummary,
@@ -33,6 +34,7 @@ import type { QuicksprintTemplateRecord } from "../contracts/quicksprint-types.j
 import type { DashboardRealtimeMutationNotifier } from "./dashboard-realtime-service.js";
 import { resolveAgentAvatarConfig } from "../contracts/agent-avatar-style.js";
 import { defaultCodingAgentMcpAccess } from "./agent-mcp-access.js";
+import type { ProjectDocsAutoEmbedService } from "./project-docs-auto-embed-service.js";
 
 export const PROJECT_SETUP_AGENT_NAME = "Project Setup Agent";
 
@@ -42,6 +44,7 @@ const DEFAULT_OPTIONS: ProjectSetupOptions = {
   previewScript: true,
   ci: true,
   techstack: true,
+  docs: false,
 };
 
 const TECHSTACK_ID_MAX_LENGTH = 80;
@@ -75,6 +78,7 @@ interface ProjectSetupServiceDeps {
   providerRunner?: IProviderRunner;
   providerConcurrencyService?: ProviderConcurrencyService;
   realtimeNotifier?: DashboardRealtimeMutationNotifier;
+  projectDocsAutoEmbedService?: Pick<ProjectDocsAutoEmbedService, "embedProjectDocs">;
   logger?: Logger;
   projectRoot?: string;
   getGithubToken?: () => string | undefined;
@@ -120,10 +124,7 @@ export class ProjectSetupService {
 
   async setupProject(
     projectId: string,
-    input?: {
-      options?: Partial<ProjectSetupOptions>;
-      clientRequestId?: string;
-    },
+    input?: ProjectSetupRequestInput,
     signal?: AbortSignal,
   ): Promise<ProjectSetupResult> {
     const prepared = await this.prepareSetupRun(projectId, input);
@@ -132,10 +133,7 @@ export class ProjectSetupService {
 
   async startProjectSetup(
     projectId: string,
-    input?: {
-      options?: Partial<ProjectSetupOptions>;
-      clientRequestId?: string;
-    },
+    input?: ProjectSetupRequestInput,
   ): Promise<ProjectSetupStartResult> {
     const prepared = await this.prepareSetupRun(projectId, input);
     void this.executePreparedSetupRun(prepared).catch((error) => {
@@ -155,10 +153,7 @@ export class ProjectSetupService {
 
   private async prepareSetupRun(
     projectId: string,
-    input?: {
-      options?: Partial<ProjectSetupOptions>;
-      clientRequestId?: string;
-    },
+    input?: ProjectSetupRequestInput,
   ): Promise<PreparedProjectSetupRun> {
     const project = this.deps.projectManagementRepository.getProject(projectId);
     if (!project) {
@@ -332,6 +327,7 @@ export class ProjectSetupService {
 
       const payload = this.parsePayload(result.text || result.stdout || result.usageTelemetry.transcriptText);
       const applied = await this.applyArtifacts(projectId, project.baseDir, options, payload);
+      const embeddedDocs = await this.embedRequestedDocs(projectId, project.baseDir, options);
 
       if (invocationId) {
         this.deps.executionRepository?.updateExecutionInvocation(invocationId, {
@@ -349,6 +345,7 @@ export class ProjectSetupService {
         agentId: setupAgent.id,
         summary: payload.summary || "Project setup completed.",
         ...applied,
+        ...embeddedDocs,
       };
     } catch (error) {
       if (invocationId) {
@@ -369,9 +366,50 @@ export class ProjectSetupService {
       previewScript: options?.previewScript ?? DEFAULT_OPTIONS.previewScript,
       ci: options?.ci ?? DEFAULT_OPTIONS.ci,
       techstack: options?.techstack ?? DEFAULT_OPTIONS.techstack,
+      docs: options?.docs ?? DEFAULT_OPTIONS.docs,
     };
   }
 
+  private async embedRequestedDocs(
+    projectId: string,
+    projectBaseDir: string,
+    options: ProjectSetupOptions,
+  ): Promise<Pick<ProjectSetupResult, "embeddedDocumentIds" | "embeddedDocumentErrors">> {
+    if (!options.docs) {
+      return { embeddedDocumentIds: [], embeddedDocumentErrors: [] };
+    }
+
+    if (!this.deps.projectDocsAutoEmbedService) {
+      return {
+        embeddedDocumentIds: [],
+        embeddedDocumentErrors: [
+          {
+            fileName: "docs",
+            error: "Project docs auto-embed service is not available.",
+          },
+        ],
+      };
+    }
+
+    try {
+      const result = await this.deps.projectDocsAutoEmbedService.embedProjectDocs(projectId, projectBaseDir);
+      return {
+        embeddedDocumentIds: result.documentIds,
+        embeddedDocumentErrors: result.errors,
+      };
+    } catch (error) {
+      return {
+        embeddedDocumentIds: [],
+        embeddedDocumentErrors: [
+          {
+            fileName: "docs",
+            error: error instanceof Error ? error.message : String(error),
+          },
+        ],
+      };
+    }
+  }
+
   private async ensureProjectSetupAgent(projectId: string): Promise<AgentPresetRecord> {
     const presets = await this.deps.agentPresetSyncService.listAgentPresets(projectId);
     const existing = presets.find((preset) => preset.name.trim().toLowerCase() === PROJECT_SETUP_AGENT_NAME.toLowerCase());
diff --git a/tests/backend/mcp/management-project-actions.test.ts b/tests/backend/mcp/management-project-actions.test.ts
index a3e2972381..929e55f7a5 100644
--- a/tests/backend/mcp/management-project-actions.test.ts
+++ b/tests/backend/mcp/management-project-actions.test.ts
@@ -73,4 +73,56 @@ describe("handleProjectAction", () => {
     expect(repository.deleteProject).toHaveBeenCalledWith("p1");
     expect(result.result).toEqual({ status: "success", deletedProjectId: "p1" });
   });
+
+  it("passes top-level setup options through to project setup", async () => {
+    const projectSetupService = {
+      setupProject: vi.fn(async () => ({ ok: true, embeddedDocumentIds: ["doc-1"], embeddedDocumentErrors: [] })),
+    };
+
+    await handleProjectAction(
+      "setup",
+      {
+        projectId: "p1",
+        options: { docs: true },
+        clientRequestId: "setup-top-level",
+      },
+      repository,
+      "projects",
+      undefined,
+      projectSetupService as any,
+    );
+
+    expect(projectSetupService.setupProject).toHaveBeenCalledWith("p1", {
+      clientRequestId: "setup-top-level",
+      options: { docs: true },
+    });
+  });
+
+  it("passes nested setup options through to project setup", async () => {
+    const projectSetupService = {
+      setupProject: vi.fn(async () => ({ ok: true, embeddedDocumentIds: ["doc-1"], embeddedDocumentErrors: [] })),
+    };
+
+    await handleProjectAction(
+      "setup",
+      {
+        projectId: "p1",
+        setup: {
+          enabled: true,
+          clientRequestId: "setup-nested",
+          options: { docs: true },
+        },
+      },
+      repository,
+      "projects",
+      undefined,
+      projectSetupService as any,
+    );
+
+    expect(projectSetupService.setupProject).toHaveBeenCalledWith("p1", {
+      enabled: true,
+      clientRequestId: "setup-nested",
+      options: { docs: true },
+    });
+  });
 });
diff --git a/tests/backend/server/request-parsers.test.ts b/tests/backend/server/request-parsers.test.ts
index 8b87411c77..7815aa8390 100644
--- a/tests/backend/server/request-parsers.test.ts
+++ b/tests/backend/server/request-parsers.test.ts
@@ -302,7 +302,7 @@ describe("Request Parsers", () => {
   });
 
   describe("parseProjectSetupRequestInput", () => {
-    it("parses setup option booleans including techstack", () => {
+    it("parses setup option booleans including techstack and docs", () => {
       expect(parseProjectSetupRequestInput({
         enabled: true,
         clientRequestId: " setup-1 ",
@@ -312,6 +312,7 @@ describe("Request Parsers", () => {
           previewScript: 1,
           ci: 0,
           techstack: true,
+          docs: true,
         },
       })).toEqual({
         enabled: true,
@@ -322,6 +323,7 @@ describe("Request Parsers", () => {
           previewScript: true,
           ci: false,
           techstack: true,
+          docs: true,
         },
       });
     });
diff --git a/tests/backend/services/project-docs-auto-embed-service.test.ts b/tests/backend/services/project-docs-auto-embed-service.test.ts
new file mode 100644
index 0000000000..32dee205f2
--- /dev/null
+++ b/tests/backend/services/project-docs-auto-embed-service.test.ts
@@ -0,0 +1,192 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+import { ProjectDocsAutoEmbedService } from "../../../src/services/project-docs-auto-embed-service.js";
+import type { IngestDocumentRequest } from "../../../src/services/knowledge-service.js";
+
+const tempDirs: string[] = [];
+
+interface IngestCall {
+  projectId: string;
+  request: IngestDocumentRequest;
+}
+
+function createKnowledgeServiceMock(options: { failOn?: string } = {}) {
+  const calls: IngestCall[] = [];
+  const ingestDocument = vi.fn(async (projectId: string, request: IngestDocumentRequest) => {
+    calls.push({ projectId, request });
+    if (request.sourceRef === options.failOn) {
+      throw new Error(`failed ${request.sourceRef}`);
+    }
+    return {
+      id: `doc-${calls.length}`,
+      projectId,
+      title: request.title,
+      sourceType: request.sourceType,
+      sourceRef: request.sourceRef ?? null,
+      mimeType: request.mimeType ?? "text/plain",
+      byteSize: request.buffer?.byteLength ?? 0,
+      charCount: request.buffer?.byteLength ?? 0,
+      tokenCount: 1,
+      summary: "",
+      contentHash: `hash-${calls.length}`,
+      status: "pending" as const,
+      embeddingModel: null,
+      chunkCount: 0,
+      errorMessage: null,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    };
+  });
+
+  return { knowledgeService: { ingestDocument }, calls };
+}
+
+async function createTempProject(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "code-ux-auto-docs-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function writeProjectFile(projectRoot: string, relativePath: string, content: string): Promise<void> {
+  const filePath = path.join(projectRoot, ...relativePath.split("/"));
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content, "utf8");
+}
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+describe("ProjectDocsAutoEmbedService", () => {
+  it("discovers documentation files in deterministic order and passes repo_path payloads", async () => {
+    const projectRoot = await createTempProject();
+    await writeProjectFile(projectRoot, "README.md", "# Readme");
+    await writeProjectFile(projectRoot, "CHANGELOG.md", "# Changelog");
+    await writeProjectFile(projectRoot, "CONTRIBUTING.md", "# Contributing");
+    await writeProjectFile(projectRoot, "AGENTS.md", "# Agents");
+    await writeProjectFile(projectRoot, "GEMINI.md", "# Gemini");
+    await writeProjectFile(projectRoot, "CLAUDE.md", "# Claude");
+    await writeProjectFile(projectRoot, "docs/guide.md", "# Guide");
+    await writeProjectFile(projectRoot, "docs/nested/page.mdx", "# Page");
+    await writeProjectFile(projectRoot, "docs/reference.html", "<h1>Reference</h1>");
+    await writeProjectFile(projectRoot, "docs/source.ts", "export const source = true;");
+    await writeProjectFile(projectRoot, "src/index.ts", "export const app = true;");
+
+    const { knowledgeService, calls } = createKnowledgeServiceMock();
+    const service = new ProjectDocsAutoEmbedService(knowledgeService);
+
+    const result = await service.embedProjectDocs("project-1", projectRoot);
+
+    expect(result.errors).toEqual([]);
+    expect(result.documentIds).toEqual([
+      "doc-1",
+      "doc-2",
+      "doc-3",
+      "doc-4",
+      "doc-5",
+      "doc-6",
+      "doc-7",
+      "doc-8",
+      "doc-9",
+    ]);
+    expect(calls.map((call) => call.request.sourceRef)).toEqual([
+      "AGENTS.md",
+      "CHANGELOG.md",
+      "CLAUDE.md",
+      "CONTRIBUTING.md",
+      "GEMINI.md",
+      "README.md",
+      "docs/guide.md",
+      "docs/nested/page.mdx",
+      "docs/reference.html",
+    ]);
+    expect(calls[0]).toMatchObject({
+      projectId: "project-1",
+      request: {
+        title: "AGENTS.md",
+        sourceType: "repo_path",
+        sourceRef: "AGENTS.md",
+      },
+    });
+    expect(calls[0].request.buffer?.toString("utf8")).toBe("# Agents");
+  });
+
+  it("ignores generated, dependency, VCS, cache, and embedding output directories", async () => {
+    const projectRoot = await createTempProject();
+    await writeProjectFile(projectRoot, "docs/visible.md", "# Visible");
+    await writeProjectFile(projectRoot, "docs/.git/hidden.md", "# Git");
+    await writeProjectFile(projectRoot, "docs/node_modules/hidden.md", "# Dependencies");
+    await writeProjectFile(projectRoot, "docs/dist/hidden.md", "# Dist");
+    await writeProjectFile(projectRoot, "docs/build/hidden.md", "# Build");
+    await writeProjectFile(projectRoot, "docs/coverage/hidden.md", "# Coverage");
+    await writeProjectFile(projectRoot, "docs/.cache/hidden.md", "# Cache");
+    await writeProjectFile(projectRoot, "docs/.turbo/hidden.md", "# Turbo");
+    await writeProjectFile(projectRoot, "docs/.next/hidden.md", "# Next");
+    await writeProjectFile(projectRoot, "docs/.output/hidden.md", "# Output");
+    await writeProjectFile(projectRoot, "docs/.code-ux/embeddings/hidden.md", "# Embeddings");
+
+    const { knowledgeService, calls } = createKnowledgeServiceMock();
+    const service = new ProjectDocsAutoEmbedService(knowledgeService);
+
+    const result = await service.embedProjectDocs("project-1", projectRoot);
+
+    expect(result.errors).toEqual([]);
+    expect(calls.map((call) => call.request.sourceRef)).toEqual(["docs/visible.md"]);
+  });
+
+  it("skips symlinks so linked docs cannot escape the project root", async () => {
+    const projectRoot = await createTempProject();
+    const outsideRoot = await createTempProject();
+    await writeProjectFile(projectRoot, "docs/visible.md", "# Visible");
+    await writeProjectFile(outsideRoot, "outside.md", "# Outside");
+    await fs.symlink(path.join(outsideRoot, "outside.md"), path.join(projectRoot, "docs", "outside.md"));
+
+    const { knowledgeService, calls } = createKnowledgeServiceMock();
+    const service = new ProjectDocsAutoEmbedService(knowledgeService);
+
+    const result = await service.embedProjectDocs("project-1", projectRoot);
+
+    expect(calls.map((call) => call.request.sourceRef)).toEqual(["docs/visible.md"]);
+    expect(result.documentIds).toEqual(["doc-1"]);
+    expect(result.errors).toEqual([
+      { fileName: "docs/outside.md", error: "Skipped symbolic link" },
+    ]);
+  });
+
+  it("collects ingestion failures without dropping successfully ingested documents", async () => {
+    const projectRoot = await createTempProject();
+    await writeProjectFile(projectRoot, "docs/fails.md", "# Fails");
+    await writeProjectFile(projectRoot, "docs/succeeds.md", "# Succeeds");
+
+    const { knowledgeService } = createKnowledgeServiceMock({ failOn: "docs/fails.md" });
+    const service = new ProjectDocsAutoEmbedService(knowledgeService);
+
+    const result = await service.embedProjectDocs("project-1", projectRoot);
+
+    expect(result.documentIds).toEqual(["doc-2"]);
+    expect(result.errors).toEqual([
+      { fileName: "docs/fails.md", error: "failed docs/fails.md" },
+    ]);
+  });
+
+  it("reports truncation when the selected documentation file limit is reached", async () => {
+    const projectRoot = await createTempProject();
+    await writeProjectFile(projectRoot, "AGENTS.md", "# Agents");
+    await writeProjectFile(projectRoot, "README.md", "# Readme");
+    await writeProjectFile(projectRoot, "docs/guide.md", "# Guide");
+
+    const { knowledgeService, calls } = createKnowledgeServiceMock();
+    const service = new ProjectDocsAutoEmbedService(knowledgeService, { maxFiles: 1 });
+
+    const result = await service.embedProjectDocs("project-1", projectRoot);
+
+    expect(calls.map((call) => call.request.sourceRef)).toEqual(["AGENTS.md"]);
+    expect(result.documentIds).toEqual(["doc-1"]);
+    expect(result.errors).toEqual([
+      { fileName: "README.md", error: "Documentation discovery truncated at 1 files" },
+    ]);
+  });
+});
diff --git a/tests/backend/services/project-setup-prompt-builder.test.ts b/tests/backend/services/project-setup-prompt-builder.test.ts
index 70253e1ee2..148341031b 100644
--- a/tests/backend/services/project-setup-prompt-builder.test.ts
+++ b/tests/backend/services/project-setup-prompt-builder.test.ts
@@ -52,6 +52,7 @@ const options = (techstack: boolean): ProjectSetupOptions => ({
   previewScript: false,
   ci: false,
   techstack,
+  docs: false,
 });
 
 const designGuidance: DesignGuidanceSettings = {
@@ -118,6 +119,19 @@ describe("buildProjectSetupPrompt", () => {
     expect(prompt).toContain("Set `techstack` to null.");
   });
 
+  it("labels docs embedding as a Code UX-applied setup option", () => {
+    const prompt = buildProjectSetupPrompt({
+      project,
+      setupAgent,
+      options: { ...options(false), docs: true },
+    });
+
+    expect(prompt).toContain("Requested artifacts: Docs Embedding");
+    expect(prompt).toContain("Code UX will automatically discover repository documentation and embed it into the Knowledge docs library");
+    expect(prompt).toContain("### Docs Embedding Rules");
+    expect(prompt).toContain("Do not include embedded documents, document contents, or knowledge-library writes in the JSON output.");
+  });
+
   it("includes selected project guidance before setup task instructions", () => {
     const prompt = buildProjectSetupPrompt({
       project,
diff --git a/tests/backend/services/project-setup-service.test.ts b/tests/backend/services/project-setup-service.test.ts
index 0135bffda5..58545d64b2 100644
--- a/tests/backend/services/project-setup-service.test.ts
+++ b/tests/backend/services/project-setup-service.test.ts
@@ -1,7 +1,7 @@
 import * as fs from "fs/promises";
 import * as os from "os";
 import * as path from "path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { AppDbStorage } from "../../../src/repositories/app-db-storage.js";
 import { ProjectManagementRepository } from "../../../src/repositories/project-management-repository.js";
 import { SettingsRepository } from "../../../src/repositories/settings-repository.js";
@@ -10,6 +10,7 @@ import { ExecutionRepository } from "../../../src/repositories/execution-reposit
 import { AgentPresetSyncService } from "../../../src/services/agent-preset-sync-service.js";
 import { QuicksprintService } from "../../../src/services/quicksprint-service.js";
 import { ProjectSetupService } from "../../../src/services/project-setup-service.js";
+import type { ProjectDocsAutoEmbedService } from "../../../src/services/project-docs-auto-embed-service.js";
 import type { IProviderRunner, ProviderRunResult } from "../../../src/infrastructure/providers/cli/provider-runner.js";
 import { DEFAULT_PLAYWRIGHT_MCP_SERVER_ID } from "../../../src/repositories/settings-defaults.js";
 
@@ -99,6 +100,7 @@ class DeferredProviderRunner implements IProviderRunner {
 async function createProjectSetupHarness(
   fixtureName: string,
   providerPayload: unknown,
+  projectDocsAutoEmbedService?: Pick<ProjectDocsAutoEmbedService, "embedProjectDocs">,
 ) {
   const repoDir = await fs.mkdtemp(path.join(os.tmpdir(), fixtureName));
   tempDirs.push(repoDir);
@@ -138,6 +140,7 @@ async function createProjectSetupHarness(
     executionRepository,
     agentPresetSyncService,
     providerRunner,
+    projectDocsAutoEmbedService,
     projectRoot: process.cwd(),
   });
 
@@ -622,4 +625,90 @@ describe("ProjectSetupService", () => {
       applicationKind: "web",
     });
   });
+
+  it("does not embed project docs when docs setup is omitted", async () => {
+    const projectDocsAutoEmbedService = {
+      embedProjectDocs: vi.fn(async () => ({ documentIds: ["doc-1"], errors: [] })),
+    } satisfies Pick<ProjectDocsAutoEmbedService, "embedProjectDocs">;
+    const { project, service } = await createProjectSetupHarness(
+      "code-ux-project-setup-docs-omitted-",
+      {
+        summary: "No docs requested.",
+        agents: [],
+        quicksprints: [],
+        previewScript: null,
+        ci: [],
+        techstack: null,
+      },
+      projectDocsAutoEmbedService,
+    );
+
+    const result = await service.setupProject(project.id, {
+      options: { agents: false, quicksprints: false, previewScript: false, ci: false, techstack: false },
+    });
+
+    expect(projectDocsAutoEmbedService.embedProjectDocs).not.toHaveBeenCalled();
+    expect(result.embeddedDocumentIds).toEqual([]);
+    expect(result.embeddedDocumentErrors).toEqual([]);
+  });
+
+  it("embeds project docs only when requested and returns document metadata", async () => {
+    const projectDocsAutoEmbedService = {
+      embedProjectDocs: vi.fn(async () => ({
+        documentIds: ["doc-readme", "doc-guide"],
+        errors: [{ fileName: "docs/broken.md", error: "Failed to ingest file" }],
+      })),
+    } satisfies Pick<ProjectDocsAutoEmbedService, "embedProjectDocs">;
+    const { project, providerRunner, service } = await createProjectSetupHarness(
+      "code-ux-project-setup-docs-enabled-",
+      {
+        summary: "Docs requested.",
+        agents: [],
+        quicksprints: [],
+        previewScript: null,
+        ci: [],
+        techstack: null,
+      },
+      projectDocsAutoEmbedService,
+    );
+
+    const result = await service.setupProject(project.id, {
+      options: { agents: false, quicksprints: false, previewScript: false, ci: false, techstack: false, docs: true },
+    });
+
+    expect(projectDocsAutoEmbedService.embedProjectDocs).toHaveBeenCalledWith(project.id, project.baseDir);
+    expect(providerRunner.lastPrompt).toContain("Requested artifacts: Docs Embedding");
+    expect(result.embeddedDocumentIds).toEqual(["doc-readme", "doc-guide"]);
+    expect(result.embeddedDocumentErrors).toEqual([{ fileName: "docs/broken.md", error: "Failed to ingest file" }]);
+    expect(result.createdAgentIds).toEqual([]);
+    expect(result.createdQuicksprintTemplateIds).toEqual([]);
+    expect(result.writtenFiles).toEqual([]);
+  });
+
+  it("reports a docs setup error when docs are requested but the embed service is unavailable", async () => {
+    const { project, service } = await createProjectSetupHarness(
+      "code-ux-project-setup-docs-unavailable-",
+      {
+        summary: "Docs requested without service.",
+        agents: [],
+        quicksprints: [],
+        previewScript: null,
+        ci: [],
+        techstack: null,
+      },
+    );
+
+    const result = await service.setupProject(project.id, {
+      options: { agents: false, quicksprints: false, previewScript: false, ci: false, techstack: false, docs: true },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.embeddedDocumentIds).toEqual([]);
+    expect(result.embeddedDocumentErrors).toEqual([
+      {
+        fileName: "docs",
+        error: "Project docs auto-embed service is not available.",
+      },
+    ]);
+  });
 });
diff --git a/tests/dashboard/v2/add-project-modal.test.tsx b/tests/dashboard/v2/add-project-modal.test.tsx
index bbda5aafc6..7713b9670b 100644
--- a/tests/dashboard/v2/add-project-modal.test.tsx
+++ b/tests/dashboard/v2/add-project-modal.test.tsx
@@ -87,6 +87,7 @@ describe("AddProjectModal", () => {
     expect(screen.getByRole("button", { name: /local repo/i })).toBeInTheDocument();
     expect(screen.getByRole("button", { name: /remote repo/i })).toBeInTheDocument();
     expect(screen.queryByText(/Initialize with Project Setup Agent/i)).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /Docs/i })).not.toBeInTheDocument();
   });
 
   it("hides git inputs and allows a blank local directory path", async () => {
@@ -119,11 +120,83 @@ describe("AddProjectModal", () => {
           previewScript: false,
           ci: true,
           techstack: true,
+          docs: false,
         },
       },
     });
   });
 
+  it("renders the Docs setup option and submits docs only when selected", async () => {
+    const onAdd = vi.fn().mockResolvedValue(undefined);
+    render(<AddProjectModal onClose={vi.fn()} onAdd={onAdd} />);
+
+    const nameInput = screen.getByLabelText(/Project Name/i);
+    fireEvent.input(nameInput, { target: { value: "Docs Project" } });
+    await waitFor(() => expect(nameInput).toHaveValue("Docs Project"));
+
+    const form = nameInput.closest("form");
+    fireEvent.submit(form!);
+
+    const docsOption = screen.getByRole("button", { name: /Docs/i });
+    expect(docsOption).toHaveAttribute("aria-pressed", "false");
+    expect(onAdd).not.toHaveBeenCalled();
+
+    fireEvent.click(docsOption);
+    expect(docsOption).toHaveAttribute("aria-pressed", "true");
+
+    fireEvent.submit(form!);
+
+    await waitFor(() => expect(onAdd).toHaveBeenCalledTimes(1));
+    expect(onAdd).toHaveBeenCalledWith({
+      name: "Docs Project",
+      type: "local",
+      path: "",
+      setup: {
+        enabled: true,
+        options: {
+          agents: true,
+          quicksprints: true,
+          previewScript: false,
+          ci: true,
+          techstack: true,
+          docs: true,
+        },
+      },
+    });
+  });
+
+  it("includes Docs when selecting all setup options", async () => {
+    const onAdd = vi.fn().mockResolvedValue(undefined);
+    render(<AddProjectModal onClose={vi.fn()} onAdd={onAdd} />);
+
+    const nameInput = screen.getByLabelText(/Project Name/i);
+    fireEvent.input(nameInput, { target: { value: "All Setup Project" } });
+    await waitFor(() => expect(nameInput).toHaveValue("All Setup Project"));
+
+    const form = nameInput.closest("form");
+    fireEvent.submit(form!);
+
+    fireEvent.click(screen.getByRole("button", { name: "All" }));
+    expect(screen.getByRole("button", { name: /Docs/i })).toHaveAttribute("aria-pressed", "true");
+
+    fireEvent.submit(form!);
+
+    await waitFor(() => expect(onAdd).toHaveBeenCalledTimes(1));
+    expect(onAdd).toHaveBeenCalledWith(expect.objectContaining({
+      setup: {
+        enabled: true,
+        options: {
+          agents: true,
+          quicksprints: true,
+          previewScript: true,
+          ci: true,
+          techstack: true,
+          docs: true,
+        },
+      },
+    }));
+  });
+
   it("submits the new project local payload without a slug", async () => {
     const onAdd = vi.fn().mockResolvedValue(undefined);
     render(<AddProjectModal onClose={vi.fn()} onAdd={onAdd} initialSourceType="new_project" />);
diff --git a/tests/dashboard/v2/projects-page.test.tsx b/tests/dashboard/v2/projects-page.test.tsx
index a0ebc3fb87..819fc4e2b1 100644
--- a/tests/dashboard/v2/projects-page.test.tsx
+++ b/tests/dashboard/v2/projects-page.test.tsx
@@ -2,11 +2,12 @@
 /** @jsx h */
 import { h } from "preact";
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { cleanup, fireEvent, render, screen } from "@testing-library/preact";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/preact";
 import * as matchers from "@testing-library/jest-dom/matchers";
 import { ProjectsPage } from "../../../dashboard/src/v2/ProjectsPage.js";
 import { useProjectData } from "../../../dashboard/src/v2/context/project-data.js";
 import { useToast } from "../../../dashboard/src/v2/components/feedback/ToastProvider.js";
+import { startProjectSetup } from "../../../dashboard/src/v2/lib/project-api.js";
 
 expect.extend(matchers);
 
@@ -139,6 +140,12 @@ describe("ProjectsPage", () => {
     cleanup();
     vi.useRealTimers();
     vi.clearAllMocks();
+    vi.mocked(startProjectSetup).mockResolvedValue({
+      accepted: true,
+      projectId: "project-1",
+      invocationId: "invocation-1",
+      agentId: "agent-1",
+    });
     vi.mocked(useToast).mockReturnValue({ addToast: vi.fn() } as any);
     vi.mocked(useProjectData).mockReturnValue({
       projects: [createProject()],
@@ -397,4 +404,43 @@ describe("ProjectsPage", () => {
     techstackOption.focus();
     expect(document.activeElement).toBe(techstackOption);
   });
+
+  it("renders Docs disabled by default and submits docs false when untouched", async () => {
+    render(<ProjectsPage />);
+
+    fireEvent.click(screen.getByRole("button", { name: /Setup project/i }));
+
+    const docsOption = screen.getByRole("button", { name: /Docs/i });
+    expect(docsOption).toHaveAttribute("aria-pressed", "false");
+
+    fireEvent.click(screen.getByRole("button", { name: "Setup Project" }));
+
+    await waitFor(() => expect(startProjectSetup).toHaveBeenCalledWith("project-1", {
+      enabled: true,
+      options: expect.objectContaining({
+        docs: false,
+      }),
+    }));
+  });
+
+  it("toggles Docs without starting setup and includes docs true in the setup payload", async () => {
+    render(<ProjectsPage />);
+
+    fireEvent.click(screen.getByRole("button", { name: /Setup project/i }));
+
+    const docsOption = screen.getByRole("button", { name: /Docs/i });
+    fireEvent.click(docsOption);
+
+    expect(startProjectSetup).not.toHaveBeenCalled();
+    expect(docsOption).toHaveAttribute("aria-pressed", "true");
+
+    fireEvent.click(screen.getByRole("button", { name: "Setup Project" }));
+
+    await waitFor(() => expect(startProjectSetup).toHaveBeenCalledWith("project-1", {
+      enabled: true,
+      options: expect.objectContaining({
+        docs: true,
+      }),
+    }));
+  });
 });