docs: fix broken site images + in-body links + Slack app-install wording (#90)

Three docs-site fixes:

1. Missing Slack setup images (the #90 report). The sync script rewrites
   `../imgs/foo.png` to an absolute `/<base>/imgs/foo.png` URL served from
   `docs/public/`, but never copied `docs/imgs/` → `docs/public/imgs/` — so
   the four Slack screenshots 404'd on the published site. Add a
   `copyAssetDir` step that mirrors source `imgs/` and `diagrams/` into
   `public/`, and commit the copied assets. Prevents recurrence for any
   future image.

2. Broken in-body design-doc links site-wide. `rewriteDocsLinkTarget`
   emitted bare root-relative routes (`/architecture/foo`) with no base
   prefix, so they resolved to the domain root and 404'd under the project
   base path. Starlight prefixes its own nav links automatically but not
   our rewritten markdown-body links. Prepend `docsBase` to every rewritten
   target (same prefix the image rewrite already uses). Re-synced all
   mirrors — the large diff is purely the base-path prefix on existing links.

3. Reword the Slack prerequisite away from "use a personal free workspace
   if your corporate Slack restricts app installs" — we don't want to
   suggest bypassing org controls. Now points users to request admin
   approval through their Slack administrator.

Author: bgagent

docs/guides/SLACK_SETUP_GUIDE.md

@@ -6,7 +6,7 @@ This guide walks through setting up the ABCA Slack integration. Once configured,
 
 - ABCA CDK stack deployed (see [Developer guide](./DEVELOPER_GUIDE.md))
 - A Cognito user account configured (see [User guide](./USER_GUIDE.md))
-- A Slack workspace where you can install apps (use a personal free workspace if your corporate Slack restricts app installs)
+- A Slack workspace where you are authorized to install apps (if your workspace requires admin approval for app installs, request it through your Slack administrator)
 - AWS CLI configured with credentials for your ABCA account
 
 ## Quick start

docs/public/diagrams/interactive-agents-phases.drawio

@@ -99,7 +99,17 @@ function ensureFrontmatter(content, title) {
     .replaceAll('../diagrams/', `${docsBase}/diagrams/`)
     .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (match, label, target) => {
       const rewritten = rewriteDocsLinkTarget(target);
-      return rewritten ? `[${label}](${rewritten})` : match;
+      if (!rewritten) {
+        return match;
+      }
+      // The site is served under `base` (docsBase), so root-relative routes
+      // must carry that prefix — otherwise they resolve to the domain root
+      // and 404. Starlight prefixes its own nav links automatically, but our
+      // rewritten body links are raw markdown and need it added explicitly
+      // (same reason the image rewrites above include docsBase). Anchors
+      // (`#…`) stay untouched. (Fixes the broken in-body design-doc links.)
+      const prefixed = rewritten.startsWith('#') ? rewritten : `${docsBase}${rewritten}`;
+      return `[${label}](${prefixed})`;
     });
 
   const trimmed = normalized.trimStart();
@@ -156,6 +166,25 @@ function mirrorDirectory(sourceDir, targetDirRelative) {
   }
 }
 
+// Recursively copy a source asset directory into the site's public/ tree so
+// every committed image/diagram is served at its rewritten absolute URL.
+// Filenames are preserved verbatim (markdown references them as-is).
+function copyAssetDir(sourceDir, targetDir) {
+  if (!fs.existsSync(sourceDir)) {
+    return;
+  }
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const from = path.join(sourceDir, entry.name);
+    const to = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyAssetDir(from, to);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
 function splitGuide(sourcePath, targetDirRelative, introTitle) {
   if (!fs.existsSync(sourcePath)) {
     return;
@@ -279,5 +308,13 @@ mirrorDirectory(path.join(docsRoot, 'design'), path.join('src', 'content', 'docs
 // --- Decision records (ADRs): mirror to decisions/ ---
 mirrorDirectory(path.join(docsRoot, 'decisions'), path.join('src', 'content', 'docs', 'decisions'));
 
+// --- Static assets: copy source image/diagram dirs into the site's public/ ---
+// Guides reference images as `../imgs/foo.png`; rewriteContent() turns those
+// into absolute `/<base>/imgs/foo.png` URLs, which Astro serves from public/.
+// Copy the source dirs here so every committed asset is published — otherwise
+// a new image lands in docs/imgs/ but 404s on the site (the cause of #90).
+copyAssetDir(path.join(docsRoot, 'imgs'), path.join(docsRoot, 'public', 'imgs'));
+copyAssetDir(path.join(docsRoot, 'diagrams'), path.join(docsRoot, 'public', 'diagrams'));
+
 // Guardrail: ensure target tree exists when running in a clean checkout.
 fs.mkdirSync(targetRoot, { recursive: true });

docs/public/diagrams/phase3-cedar-hitl.drawio

@@ -7,7 +7,7 @@ title: Api contract
 The REST API is the single entry point for all platform interactions. The CLI, webhook integrations, and any future clients use this API to submit tasks, check status, and manage integrations. This is a design-level specification; the source of truth for types is `cdk/src/handlers/shared/types.ts`.
 
 - **Use this doc for:** endpoint paths, payload shapes, auth requirements, and error codes.
-- **Related docs:** [INPUT_GATEWAY.md](/architecture/input-gateway) for the gateway's role, [ORCHESTRATOR.md](/architecture/orchestrator) for the task state machine, [SECURITY.md](/architecture/security) for the authentication model.
+- **Related docs:** [INPUT_GATEWAY.md](/sample-autonomous-cloud-coding-agents/architecture/input-gateway) for the gateway's role, [ORCHESTRATOR.md](/sample-autonomous-cloud-coding-agents/architecture/orchestrator) for the task state machine, [SECURITY.md](/sample-autonomous-cloud-coding-agents/architecture/security) for the authentication model.
 
 ## Base URL
 
@@ -310,7 +310,7 @@ Returns a summary subset of fields. Use `GET /v1/tasks/{task_id}` for full detai
 DELETE /v1/tasks/{task_id}
 ```
 
-Cancels a task. See [ORCHESTRATOR.md](/architecture/orchestrator) for cancellation behavior by state.
+Cancels a task. See [ORCHESTRATOR.md](/sample-autonomous-cloud-coding-agents/architecture/orchestrator) for cancellation behavior by state.
 
 **Response: `200 OK`** — a compact confirmation body (not a full `TaskDetail`):
 

docs/public/imgs/enable-events-after.png

@@ -10,7 +10,7 @@ This document outlines the overall architecture of the platform. Each component
 
 ## Design principles
 
-For long-term direction and review tenets, see [VISION.md](/architecture/vision).
+For long-term direction and review tenets, see [VISION.md](/sample-autonomous-cloud-coding-agents/architecture/vision).
 
 - **Extensibility** - Extend the system without modifying core code. Critical components are accessed through internal interfaces (ComputeStrategy, MemoryStore) so implementations can be swapped.
 - **Flexibility** - This field moves fast. Components should be replaceable as better options emerge.
@@ -39,13 +39,13 @@ flowchart LR
 
 The orchestrator and agent are deliberately separated. The orchestrator handles everything deterministic (cheap Lambda invocations); the agent handles everything that needs LLM reasoning (expensive compute + tokens). This separation provides reliability (crashed agents don't leave orphaned state), cost efficiency (bookkeeping doesn't burn tokens), security (the agent can't bypass platform invariants), and testability (deterministic steps are unit-tested without LLM calls).
 
-For the full orchestrator design, see [ORCHESTRATOR.md](/architecture/orchestrator). For the API contract, see [API_CONTRACT.md](/architecture/api-contract).
+For the full orchestrator design, see [ORCHESTRATOR.md](/sample-autonomous-cloud-coding-agents/architecture/orchestrator). For the API contract, see [API_CONTRACT.md](/sample-autonomous-cloud-coding-agents/architecture/api-contract).
 
 ## Repository onboarding
 
 Onboarding is CDK-based. Each repository is an instance of the `Blueprint` construct in the stack. The construct writes a `RepoConfig` record to DynamoDB; the orchestrator reads it at task time.
 
-Blueprints configure how the orchestrator executes steps for each repo: compute strategy, model selection, turn limits, GitHub token, and optional custom steps. See [REPO_ONBOARDING.md](/architecture/repo-onboarding) for the full design.
+Blueprints configure how the orchestrator executes steps for each repo: compute strategy, model selection, turn limits, GitHub token, and optional custom steps. See [REPO_ONBOARDING.md](/sample-autonomous-cloud-coding-agents/architecture/repo-onboarding) for the full design.
 
 ## Model selection
 
@@ -68,7 +68,7 @@ The dominant cost is Bedrock inference + compute, not infrastructure. Memory, La
 | Medium (small team) | 200-500 | $500-3,000 |
 | High (org-wide) | 2,000-5,000 | $5,000-30,000 |
 
-For the full breakdown, see [COST_MODEL.md](/architecture/cost-model).
+For the full breakdown, see [COST_MODEL.md](/sample-autonomous-cloud-coding-agents/architecture/cost-model).
 
 ## Known architectural risks