Sprint 188: Auto Embed docs Setup Agent — merge feature/CODUX-188-auto-embed-docs-setup-agent into dev

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>

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

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,

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`.

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`

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:

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`.

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`

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:

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