Addressing Alain's feedback

Author: leandrodamascena

docs/abca-plugin/skills/setup/SKILL.md

@@ -96,4 +96,4 @@ Guide through:
 After all phases pass, summarize:
 - Stack outputs (API URL, User Pool ID, etc.)
 - Next steps: onboard a repository (use the `onboard-repo` skill)
-- Point to the User Guide: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/user-guide/introduction/
+- Point to the Quick Start: https://aws-samples.github.io/sample-autonomous-cloud-coding-agents/getting-started/quick-start/

docs/astro.config.mjs

@@ -1,12 +1,16 @@
 import { visit } from 'unist-util-visit';
 
+function escapeHtml(str) {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
 export function remarkMermaid() {
   return (tree) => {
     visit(tree, 'code', (node, index, parent) => {
       if (node.lang !== 'mermaid' || !parent) return;
       parent.children[index] = {
         type: 'html',
-        value: `<pre class="mermaid">${node.value}</pre>`,
+        value: `<pre class="mermaid">${escapeHtml(node.value)}</pre>`,
       };
     });
   };

docs/plugins/remark-mermaid.mjs

@@ -56,11 +56,19 @@ function rewriteDocsLinkTarget(target) {
     }
   }
 
-  /** Map USER_GUIDE anchors to the new `using/` directory. */
+  /** Map USER_GUIDE anchors to the new `using/` and `customizing/` directories. */
   const userGuideAnchorRoutes = {
+    overview: '/using/overview',
     authentication: '/using/authentication',
-    'repository-onboarding': '/using/repository-onboarding',
+    'repository-onboarding': '/customizing/repository-onboarding',
+    'per-repo-overrides': '/customizing/per-repo-overrides',
+    'task-types': '/using/task-types',
+    'using-the-rest-api': '/using/using-the-rest-api',
+    'using-the-cli': '/using/using-the-cli',
+    'webhook-integration': '/using/webhook-integration',
     'task-lifecycle': '/using/task-lifecycle',
+    'what-the-agent-does': '/using/what-the-agent-does',
+    'tips-for-being-a-good-citizen': '/using/tips-for-being-a-good-citizen',
   };
   if (stem === 'USER_GUIDE' && anchor) {
     const splitRoute = userGuideAnchorRoutes[anchor.toLowerCase()];
@@ -176,6 +184,26 @@ splitGuide(
   'Using the platform',
 );
 
+// Move customization pages from using/ to customizing/ (they belong under the Customizing sidebar section)
+const customizingPages = ['Repository-onboarding.md', 'Per-repo-overrides.md'];
+for (const page of customizingPages) {
+  const src = path.join(docsRoot, 'src', 'content', 'docs', 'using', page);
+  const dest = path.join(docsRoot, 'src', 'content', 'docs', 'customizing', page);
+  if (fs.existsSync(src)) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.renameSync(src, dest);
+  }
+}
+
+// Remove orphaned stubs generated by splitGuide that have no useful content
+const orphanedPages = ['Introduction.md', 'Prerequisites.md'];
+for (const page of orphanedPages) {
+  const filePath = path.join(docsRoot, 'src', 'content', 'docs', 'using', page);
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+}
+
 // --- Quick Start: mirror to getting-started/ ---
 mirrorMarkdownFile(
   path.join(docsRoot, 'guides', 'QUICK_START.md'),
@@ -201,6 +229,9 @@ mirrorMarkdownFile(
 );
 
 // --- Design docs: mirror to architecture/ ---
+// Source lives at docs/design/ but renders at /architecture/ on the site.
+// We keep the source directory named "design" because that's what CLAUDE.md and
+// AGENTS.md reference for contributors. The rename happens only at the site level.
 mirrorDirectory(path.join(docsRoot, 'design'), path.join('src', 'content', 'docs', 'architecture'));
 
 // Guardrail: ensure target tree exists when running in a clean checkout.