Add CLAUDE.md and .claude/ agent configuration

.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "project": {
+    "name": "defang-docs",
+    "description": "Defang platform documentation site (Docusaurus 3)",
+    "conventions": {
+      "language": "TypeScript, Markdown, MDX",
+      "framework": "Docusaurus 3",
+      "packageManager": "npm",
+      "styling": "Tailwind CSS, CSS Modules"
+    }
+  }
+}

CLAUDE.md

@@ -0,0 +1,307 @@
+# Defang Docs
+
+Documentation site for the Defang platform, built with **Docusaurus 3** and deployed to [docs.defang.io](https://docs.defang.io).
+
+---
+
+## Project Overview
+
+This is a static documentation site using Docusaurus 3 (`@docusaurus/core ^3.9.1`). Content is authored in Markdown/MDX under `docs/`. The site uses Tailwind CSS for custom components and shadcn/ui primitives. Search is powered by Algolia.
+
+---
+
+## Directory Structure
+
+```
+defang-docs/
+├── docs/                    # All documentation content
+│   ├── intro/               # Overview section (what-is-defang, getting-started, FAQ)
+│   ├── concepts/            # Concept explainers (compose, services, domains, etc.)
+│   ├── tutorials/           # Step-by-step guides (deploy-to-aws, scaling, etc.)
+│   ├── providers/           # Cloud provider details (aws, gcp, azure, digitalocean)
+│   ├── cli/                 # AUTO-GENERATED from defang CLI — do NOT edit by hand
+│   └── ask.md               # AI chatbot page
+├── blog/                    # Blog posts (currently disabled in config)
+├── src/
+│   ├── components/          # React components (HomepageFeatures, UI primitives)
+│   ├── css/custom.css       # Global CSS overrides
+│   ├── lib/                 # Utility functions
+│   ├── pages/               # Custom pages (index.tsx, docs.tsx)
+│   └── theme/               # Docusaurus theme overrides (Layout/)
+├── static/                  # Static assets (images, analytics, JSON feeds)
+├── scripts/
+│   ├── prebuild.sh          # Orchestrates CLI doc generation + sample ingestion
+│   ├── prep-cli-docs.js     # Post-processes auto-generated CLI docs
+│   └── prep-samples.js      # Ingests samples repo into static/samples-v2.json
+├── docusaurus.config.js     # Main Docusaurus configuration
+├── sidebars.js              # Sidebar definitions (all use autogenerated from dirs)
+├── redirects.json           # URL redirect mappings
+├── cli-index.mdx            # Template copied to docs/cli/index.mdx during prebuild
+├── tailwind.config.js       # Tailwind CSS configuration
+├── components.json          # shadcn/ui component configuration
+└── tsconfig.json            # TypeScript configuration
+```
+
+---
+
+## Build, Dev, and Preview Commands
+
+```bash
+npm install                  # Install dependencies
+npm run start                # Dev server with hot reload (runs prebuild first)
+npm run build                # Production build (runs prebuild first)
+npm run serve                # Serve the production build locally
+npm run typecheck            # TypeScript type checking
+npm run clear                # Clear Docusaurus cache
+```
+
+### Prebuild Step (Important)
+
+Both `npm run start` and `npm run build` automatically run `scripts/prebuild.sh`, which:
+
+1. Runs `go run main.go` from the **defang CLI repo** (`../defang/src/cmd/gendocs`) to auto-generate CLI reference docs into `docs/cli/`
+2. Runs `prep-cli-docs.js` to add frontmatter and escape MDX-incompatible syntax
+3. Copies `cli-index.mdx` to `docs/cli/index.mdx`
+4. Runs `prep-samples.js` to ingest sample apps from the **samples repo** (`../samples/samples`) into `static/samples-v2.json`
+
+**External repo requirements:** The prebuild expects sibling directories:
+- `../defang` — the [DefangLabs/defang](https://github.com/DefangLabs/defang) CLI repo (requires Go)
+- `../samples` — the [DefangLabs/samples](https://github.com/DefangLabs/samples) repo
+
+In CI, these are cloned into the working directory (`./defang`, `./samples`) instead.
+
+---
+
+## Content Conventions
+
+### File Naming
+
+- Use **kebab-case** for all doc files: `deploy-to-aws.mdx`, `private-endpoints.md`
+- Use `.md` for pure Markdown; use `.mdx` when importing React components or using JSX
+- Each section directory should have a `_category_.json` for sidebar metadata
+
+### Frontmatter
+
+Every doc file should have frontmatter with at least `title` and `description`:
+
+```yaml
+---
+title: Deploy to AWS
+description: Defang allows you deploy to your own Amazon Web Services (AWS) account.
+---
+```
+
+Optional frontmatter fields:
+- `sidebar_position` — override auto-generated sidebar order
+- `sidebar_label` — override the label shown in the sidebar
+- `sidebar_class_name: hidden` — hide from sidebar
+
+### Category Files
+
+Each directory under `docs/` uses a `_category_.json` to define sidebar grouping:
+
+```json
+{
+  "label": "Concepts",
+  "link": {
+    "slug": "concepts",
+    "type": "generated-index",
+    "description": "Description shown on the category index page."
+  }
+}
+```
+
+### Sidebar Configuration
+
+Sidebars are defined in `sidebars.js`. All sections use `autogenerated` from their directory:
+
+| Sidebar | Directory | Nav Label |
+|---------|-----------|-----------|
+| `mainSidebar` | `docs/intro/` | Overview |
+| `conceptsSidebar` | `docs/concepts/` | Concepts |
+| `tutorialsSidebar` | `docs/tutorials/` | Tutorials |
+| `providersSidebar` | `docs/providers/` | Providers |
+| `cliSidebar` | `docs/cli/` | CLI |
+
+To add a new doc, place it in the appropriate directory. The sidebar ordering comes from `sidebar_position` frontmatter or alphabetical order.
+
+### Linking Between Docs
+
+Use relative paths for internal links:
+
+```markdown
+See [Compose](./compose.md) for details.
+See the [Getting Started](../intro/getting-started.mdx) guide.
+```
+
+Docusaurus resolves `.md`/`.mdx` extensions automatically. The config throws on broken markdown links (`onBrokenMarkdownLinks: 'throw'`).
+
+### MDX Components
+
+When using JSX/React in docs, use `.mdx` extension and import components:
+
+```mdx
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="aws" label="AWS">
+    AWS-specific instructions here.
+  </TabItem>
+</Tabs>
+```
+
+Available custom components:
+- `src/components/ui/` — shadcn/ui primitives (badge, button, card)
+- `src/components/HomepageFeatures/` — homepage feature cards
+- `src/components/OneClick/` — one-click deploy buttons
+
+Mermaid diagrams are supported natively (configured via `@docusaurus/theme-mermaid`).
+
+### Admonitions
+
+Use Docusaurus admonition syntax:
+
+```markdown
+:::note
+This is a note.
+:::
+
+:::warning
+This is a warning.
+:::
+
+:::tip
+This is a tip.
+:::
+```
+
+---
+
+## Adding New Documentation
+
+### New Page in Existing Section
+
+1. Create a `.md` or `.mdx` file in the appropriate `docs/` subdirectory
+2. Add frontmatter with `title` and `description`
+3. Optionally set `sidebar_position` to control ordering
+4. The sidebar picks it up automatically
+
+### New Section
+
+1. Create a new directory under `docs/`
+2. Add a `_category_.json` file
+3. Add a new sidebar entry in `sidebars.js`:
+   ```js
+   newSidebar: [{ type: 'autogenerated', dirName: 'new-section' }],
+   ```
+4. Add a navbar item in `docusaurus.config.js` under `themeConfig.navbar.items`
+
+### New Redirect
+
+Add an entry to `redirects.json`:
+```json
+{ "from": "/docs/old-path", "to": "/docs/new-path" }
+```
+
+---
+
+## CLI Reference Docs
+
+**The `docs/cli/` directory is auto-generated. Do NOT edit these files by hand.**
+
+CLI docs are generated from the Go source in the `defang` repo via `gendocs`. To update CLI docs:
+1. Update the CLI source in `projects/defang`
+2. Run `npm run prebuild` (or let `npm run start`/`npm run build` do it)
+3. The generated files will be overwritten on every build
+
+The only manually maintained file is `cli-index.mdx` at the repo root, which is copied into `docs/cli/index.mdx` during prebuild.
+
+---
+
+## Style Guide
+
+### Writing Conventions
+
+- Write in **second person** ("You can deploy..." not "Users can deploy...")
+- Use **present tense** ("This command deploys..." not "This command will deploy...")
+- Keep sentences concise and direct
+- Start tutorials with a **Prerequisites** section listing requirements
+- End tutorials with clear next steps or links to related content
+- Use code blocks with language identifiers (`bash`, `yaml`, `typescript`)
+
+### CLI Command References
+
+When referencing CLI commands in docs, use backticks: `` `defang compose up` ``
+
+Always verify CLI command syntax against the actual CLI. The prebuild auto-generates CLI reference from Go source, so manual docs should stay consistent with those.
+
+### Accuracy Requirement
+
+Documentation claims about CLI behavior, compose file support, and provider capabilities MUST be verified against the actual codebase. Do not guess or assume features exist.
+
+---
+
+## CI/CD
+
+- **PR checks:** `.github/workflows/test-deploy.yml` — runs `npm ci`, prebuild, and `npm run build` on every PR to `main`
+- **Deploy:** `.github/workflows/deploy.yml` — builds and deploys to GitHub Pages on push to `main` or `repository_dispatch` events (triggered by CLI releases and sample updates)
+- The deploy workflow also notifies the docs chatbot to rebuild its index
+
+---
+
+## SAM (Simple Agent Manager) Integration
+
+When running inside SAM (detected by `$SAM_WORKSPACE_ID` environment variable):
+
+### Environment Awareness
+
+- **Ephemeral environment:** Your workspace may be destroyed at any time. Push changes frequently.
+- **Push often:** Commit and push after completing each logical unit of work, not just at the end.
+
+### SAM Tool Usage
+
+| Tool | When to Use |
+|------|-------------|
+| `update_task_status` | After completing milestones (e.g., "drafted new tutorial", "fixed broken links") |
+| `expose_port` | When running `npm run start` (port 3000) so humans can preview the dev server |
+| `create_idea` | When you discover doc improvements, missing content, or broken links during work |
+| `search_messages` | To find context from prior conversations about doc changes |
+
+### Knowledge Graph
+
+SAM maintains a persistent knowledge graph across sessions. Use it to preserve non-obvious context:
+
+| Tool | When to Use |
+|------|-------------|
+| `add_knowledge` | Store observations about user preferences (entityType: `preference`), content conventions not in CLAUDE.md (entityType: `style`), architecture decisions (entityType: `context`), or project context like feature launches and deprecations (entityType: `context`) |
+| `search_knowledge` | Before key decisions — e.g., search "ContentStyle" before writing docs, search "PlaygroundDeprecation" before referencing Playground |
+| `update_knowledge` / `remove_knowledge` | Fix stale or incorrect observations |
+| `confirm_knowledge` | When you verify an existing observation is still accurate |
+
+Do NOT store: content derivable from the docs themselves, git history, ephemeral task details, or anything already in CLAUDE.md.
+
+### Verification Discipline
+
+Documentation changes should be verified against actual behavior:
+- CLI commands: Check the generated CLI docs or the Go source in `projects/defang`
+- Portal features: Check the Portal (Web UI) codebase
+- Provider behavior: Check the BYOC provider implementations in `projects/defang`
+
+Do NOT document features that do not exist. When uncertain, note it and create an idea for follow-up.
+
+### Dev Server Preview
+
+```bash
+# Start dev server, then expose for human review
+npm run start -- --port 3000 --host 0.0.0.0
+# Then call expose_port with port 3000
+```
+
+---
+
+## Precedence
+
+1. This `CLAUDE.md` (when working in defang-docs)
+2. Root constitution (`defang-global/.specify/memory/constitution.md`)
+3. Docusaurus conventions