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

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/scripts/sync-starlight.mjs

@@ -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,12 @@ 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 dir into the site's public/ ---
+// Guides reference images as `../imgs/foo.png`; ensureFrontmatter() turns
+// those into absolute `/<base>/imgs/foo.png` URLs, which Astro serves from
+// public/. Copy the source dir here so every committed image is published —
+// otherwise a new image lands in docs/imgs/ but 404s on the site (#90).
+copyAssetDir(path.join(docsRoot, 'imgs'), path.join(docsRoot, 'public', 'imgs'));
+
 // Guardrail: ensure target tree exists when running in a clean checkout.
 fs.mkdirSync(targetRoot, { recursive: true });

docs/src/content/docs/architecture/Api-contract.md

@@ -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/src/content/docs/architecture/Architecture.md

@@ -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
 

docs/src/content/docs/architecture/Attachments.md

@@ -7,7 +7,7 @@ title: Attachments
 End-to-end support for attaching files, images, and URLs to agent tasks. Attachments let users provide non-text context — screenshots of bugs, design mockups, CSV data, log files, code snippets — that the agent can reference during execution. Every channel (CLI, webhook, Slack, Linear) feeds the same schema; every attachment passes through security screening before reaching the agent.
 
 - **Use this doc for:** understanding the attachment data model, upload flow, security screening pipeline, storage layout, agent consumption, and per-channel behaviour.
-- **Related docs:** [API_CONTRACT.md](/architecture/api-contract) for the `attachments` request schema (must be updated in tandem — see [API contract sync](#api-contract-sync)), [ORCHESTRATOR.md](/architecture/orchestrator) for the task lifecycle this extends, [SECURITY.md](/architecture/security) for guardrail and Cedar context, [ARCHITECTURE.md](/architecture/architecture) for the platform overview.
+- **Related docs:** [API_CONTRACT.md](/sample-autonomous-cloud-coding-agents/architecture/api-contract) for the `attachments` request schema (must be updated in tandem — see [API contract sync](#api-contract-sync)), [ORCHESTRATOR.md](/sample-autonomous-cloud-coding-agents/architecture/orchestrator) for the task lifecycle this extends, [SECURITY.md](/sample-autonomous-cloud-coding-agents/architecture/security) for guardrail and Cedar context, [ARCHITECTURE.md](/sample-autonomous-cloud-coding-agents/architecture/architecture) for the platform overview.
 
 ## Motivation
 
@@ -197,7 +197,7 @@ The `<attachment_id>` segment ensures uniqueness even if multiple attachments sh
 | Max inline data per attachment | 500 KB decoded | The Lambda synchronous invocation payload limit is **6 MB**. At 500 KB decoded (~667 KB base64) per attachment, even 5 inline attachments plus request JSON stays under 6 MB. The presigned path handles anything larger. |
 | Max total inline data per request | 3 MB decoded | Hard cap on total base64-decoded bytes in a single request. Even with base64 overhead (~4 MB encoded) plus JSON fields, this stays under the 6 MB Lambda payload limit. |
 | Max total size per task | 50 MB | Prevents abuse; bounds total screening and transfer time |
-| Max task_description length | 10,000 chars | Increased from 2,000. **This is a standalone API change that affects all tasks** (not just attachment tasks). Rationale: (a) attachments need rich explanatory context ("implement this design per the attached mockup, paying attention to the header layout"), (b) multiple users have reported the 2K limit as a friction point for complex task descriptions even without attachments, (c) the guardrail screening cost increase is minimal (text screening is cheap), (d) DynamoDB item size impact is negligible (~8 KB vs ~2 KB for the description field). **Requires updating [API_CONTRACT.md](/architecture/api-contract) line 82 in tandem.** |
+| Max task_description length | 10,000 chars | Increased from 2,000. **This is a standalone API change that affects all tasks** (not just attachment tasks). Rationale: (a) attachments need rich explanatory context ("implement this design per the attached mockup, paying attention to the header layout"), (b) multiple users have reported the 2K limit as a friction point for complex task descriptions even without attachments, (c) the guardrail screening cost increase is minimal (text screening is cheap), (d) DynamoDB item size impact is negligible (~8 KB vs ~2 KB for the description field). **Requires updating [API_CONTRACT.md](/sample-autonomous-cloud-coding-agents/architecture/api-contract) line 82 in tandem.** |
 | Allowed image MIME types | `image/png`, `image/jpeg` | Bedrock-supported formats; GIF/WebP removed to eliminate native image processing dependency |
 | Allowed file MIME types | `text/plain`, `text/csv`, `text/markdown`, `application/json`, `application/pdf`, `text/x-log` | Useful for code/data context; no executables |
 | Max URL fetch size | 10 MB | Same per-attachment limit for fetched content |
@@ -1437,7 +1437,7 @@ The `upload_url` and `upload_expires_at` fields are only present in the initial
 
 ## API contract sync
 
-This design introduces changes that conflict with the current [API_CONTRACT.md](/architecture/api-contract). The following updates must be made to API_CONTRACT.md in tandem with implementation:
+This design introduces changes that conflict with the current [API_CONTRACT.md](/sample-autonomous-cloud-coding-agents/architecture/api-contract). The following updates must be made to API_CONTRACT.md in tandem with implementation:
 
 | Section | Current value | New value |
 |---|---|---|

docs/src/content/docs/architecture/Cedar-hitl-gates.md

@@ -5,7 +5,7 @@ title: Cedar hitl gates
 # Cedar HITL Approval Gates
 
 > **Status:** Core implemented; this document remains the authoritative design reference.
-> **Companion:** [`INTERACTIVE_AGENTS.md`](/architecture/interactive-agents) §9.3 (pointing here), §7 (state machine).
+> **Companion:** [`INTERACTIVE_AGENTS.md`](/sample-autonomous-cloud-coding-agents/architecture/interactive-agents) §9.3 (pointing here), §7 (state machine).
 > **Visual:** [`/sample-autonomous-cloud-coding-agents/diagrams/phase3-cedar-hitl.drawio`](/sample-autonomous-cloud-coding-agents/diagrams/phase3-cedar-hitl.drawio) (12 pages; supplemented by inline Mermaid diagrams below).
 > **Design locked:** 2026-04-23 (Sam ↔ assistant discussion).
 > **Rev:** 5 (2026-05-06 — fold in parallel adversarial + advocate review of the timeout design: late-approval re-read on TIMED_OUT ConditionCheckFailed; user-visible timeout-cap milestones; ceiling-shrink milestone; Runtime JWT bound verified as auto-refreshed IAM; three new tuning metrics; explicit off-hours trade-off section; notification-delivery-failure boundary. IMPL-24 through IMPL-28 added.).

docs/src/content/docs/architecture/Compute.md

@@ -7,7 +7,7 @@ title: Compute
 Every task runs in an isolated cloud compute environment. Nothing runs on the user's machine. The agent clones the repo, writes code, runs tests, and opens a PR inside a MicroVM that is created for the task and destroyed when it ends.
 
 - **Use this doc for:** understanding the compute environment, agent harness, network architecture, and the constraints that shape the platform's design.
-- **Related docs:** [ORCHESTRATOR.md](/architecture/orchestrator) for session management and liveness monitoring, [SECURITY.md](/architecture/security) for isolation and egress controls, [REPO_ONBOARDING.md](/architecture/repo-onboarding) for per-repo compute configuration.
+- **Related docs:** [ORCHESTRATOR.md](/sample-autonomous-cloud-coding-agents/architecture/orchestrator) for session management and liveness monitoring, [SECURITY.md](/sample-autonomous-cloud-coding-agents/architecture/security) for isolation and egress controls, [REPO_ONBOARDING.md](/sample-autonomous-cloud-coding-agents/architecture/repo-onboarding) for per-repo compute configuration.
 
 ## Compute options
 
@@ -25,7 +25,7 @@ The default runtime is **Amazon Bedrock AgentCore Runtime**, which runs each ses
 | **Cost model** | vCPU-hrs + GB-hrs | vCPU + mem/sec | EC2 + EBS | EKS control + EC2 | Underlying compute | Request + duration | EC2 metal + your ops |
 | **Fit** | **Default choice** | Repos > 2 GB image | GPU, heavy toolchains | Max flexibility | Queued batch jobs | **Poor** (15 min cap) | Best potential, highest cost |
 
-The backend is selected per repo via `compute_type` in the Blueprint config. The orchestrator resolves the strategy and delegates session start, polling, and termination to the strategy implementation. See [REPO_ONBOARDING.md](/architecture/repo-onboarding) for the `ComputeStrategy` interface.
+The backend is selected per repo via `compute_type` in the Blueprint config. The orchestrator resolves the strategy and delegates session start, polling, and termination to the strategy implementation. See [REPO_ONBOARDING.md](/sample-autonomous-cloud-coding-agents/architecture/repo-onboarding) for the `ComputeStrategy` interface.
 
 ## What runs in the session
 
@@ -75,7 +75,7 @@ The platform works around this by splitting storage:
 | Max session duration | 8 hours | Hard limit enforced by AgentCore |
 | Idle timeout | 8 hours (configured) | Overridden from the default via `idleRuntimeSessionTimeout: Duration.hours(8)` so sessions blocked on long approval waits or heavy builds are not evicted while idle. Agent reports `HealthyBusy` via `/ping` to stay alive |
 
-See [ORCHESTRATOR.md](/architecture/orchestrator) for how the orchestrator handles these timeouts.
+See [ORCHESTRATOR.md](/sample-autonomous-cloud-coding-agents/architecture/orchestrator) for how the orchestrator handles these timeouts.
 
 ## Agent harness
 
@@ -109,7 +109,7 @@ The harness enforces tool-call policy via Cedar-based hooks:
 - **PreToolUse** (`agent/src/hooks.py` + `agent/src/policy.py`) - Evaluates tool calls before execution. `pr_review` agents cannot use `Write`/`Edit`. Writes to `.git/*` are blocked. Destructive bash commands are denied. Fail-closed: if Cedar is unavailable, all calls are denied.
 - **PostToolUse** (`agent/src/hooks.py` + `agent/src/output_scanner.py`) - Screens tool outputs for secrets and redacts before re-entering agent context.
 
-Per-repo custom Cedar policies are supported via Blueprint `security.cedarPolicies`. See [SECURITY.md](/architecture/security) for the full policy enforcement model.
+Per-repo custom Cedar policies are supported via Blueprint `security.cedarPolicies`. See [SECURITY.md](/sample-autonomous-cloud-coding-agents/architecture/security) for the full policy enforcement model.
 
 ## Network architecture