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

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

* docs: redact app/client IDs, verification token, and API Gateway ID in Slack setup screenshots

* docs: remove unreachable anchor guard in link rewrite (review nit)

---------

Co-authored-by: bgagent <bgagent@noreply.github.com>
Co-authored-by: Alain Krok <alkrok@amazon.com>

Author: 3 people

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/imgs/enable-events-after.png

@@ -100,7 +100,19 @@ 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). Every
+      // non-undefined return from rewriteDocsLinkTarget is a `/…` route (bare
+      // `#…` anchors and external links return undefined and keep their
+      // original text above), so the prefix always applies.
+      // (Fixes the broken in-body design-doc links.)
+      return `[${label}](${docsBase}${rewritten})`;
     });
 
   const trimmed = normalized.trimStart();
@@ -158,6 +170,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;
@@ -287,5 +318,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 });