From 84cb03ca46497aa7db2bb370f16bf01bab5f6ccb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Titsworth-Morin?= Date: Fri, 17 Apr 2026 09:48:20 +0000 Subject: [PATCH 1/4] Add CLAUDE.md and .claude/ agent configuration Comprehensive project context for AI agents including: - Docusaurus 3 framework details and directory structure - Build/dev/preview commands and prebuild pipeline - Content conventions (frontmatter, MDX, sidebar config) - Style guide and CLI doc accuracy requirements - SAM integration guidance for ephemeral environments Co-Authored-By: Claude Opus 4.6 --- .claude/settings.json | 12 ++ CLAUDE.md | 295 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 307 insertions(+) create mode 100644 .claude/settings.json create mode 100644 CLAUDE.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 000000000..79e538f6b --- /dev/null +++ b/.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" + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..f110c58f3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,295 @@ +# 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'; + + + + AWS-specific instructions here. + + +``` + +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 | +| `get_ci_status` | After pushing to verify the build passes | +| `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 | + +### 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 codebase in `projects/portal` +- 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 From 1e002a70c7e651a3e86910a94c96b26f99da729a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Titsworth-Morin?= Date: Fri, 17 Apr 2026 10:44:18 +0000 Subject: [PATCH 2/4] docs: remove private repo path reference from CLAUDE.md Replace reference to private repo path with functional description. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index f110c58f3..0d02f4cb8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -273,7 +273,7 @@ When running inside SAM (detected by `$SAM_WORKSPACE_ID` environment variable): 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 codebase in `projects/portal` +- 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. From f2c3460cbe00a4d11bcf3f1e6e0a24cac4e9779d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Titsworth-Morin?= Date: Fri, 17 Apr 2026 10:46:20 +0000 Subject: [PATCH 3/4] docs: remove get_ci_status reference Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0d02f4cb8..83de8c8cf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -265,7 +265,6 @@ When running inside SAM (detected by `$SAM_WORKSPACE_ID` environment variable): |------|-------------| | `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 | -| `get_ci_status` | After pushing to verify the build passes | | `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 | From 2d2f0abb179514bca1496db0e70a60736d3053eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Titsworth-Morin?= Date: Fri, 17 Apr 2026 10:50:02 +0000 Subject: [PATCH 4/4] docs: add SAM knowledge graph guidance to CLAUDE.md Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 83de8c8cf..5927a8dbb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -268,6 +268,19 @@ When running inside SAM (detected by `$SAM_WORKSPACE_ID` environment variable): | `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: