Writing docs

This site is Astro Starlight in docs/. Pages are Markdown or MDX files; the sidebar, search (Pagefind), dark and light themes and the API reference (starlight-openapi) come with it.

• Directorydocs/

  • astro.config.mjs Sidebar, plugins and theme
  • Directorypublic/

    • openapi.json Generated API schema
    • Directoryagent/ Agent diagram: .excalidraw source, .svg export, viewer

      • …
  • scripts/export_openapi.py Writes openapi.json from the backend
  • Directorysrc/

    • components/SystemDiagram.astro The system diagram on the architecture overview
    • Directorycontent/docs/ The pages; the path is the URL

      • Directorystart/ Setup and configuration

        • …
      • Directoryguides/ How-tos for features

        • …
      • Directoryarchitecture/

        • …
      • Directoryapi/

        • …
      • Directorycontributing/

        • …
    • styles/theme.css The portal’s colors

Run it

cd docs
pnpm install
pnpm dev     # live reload on http://localhost:4321
pnpm build   # checks every page and builds the search index

In an orb, the docs service in .amp/services.yaml serves a production build behind the MateFactory docs portal, because search only works in a build. Run amp orb service restart docs to rebuild it after an edit, or run pnpm dev on another port while you write.

Where a change goes

You changed	Update
A screen, button label or flow	The guide for that feature in guides/
An environment variable or setup step	start/configuration.md, start/local-setup.mdx or start/quickstart.mdx
A route	pnpm openapi, and api/overview.mdx for new conventions
A table or column	architecture/data-model.md
The provider interface or Daytona behavior	architecture/sandbox-providers.md
How parts connect	architecture/overview.mdx and src/components/SystemDiagram.astro
The desktop app (desktop/)	start/desktop-app.mdx for setup and packaging; architecture/desktop.md for how it works
The Android app (android/)	start/android-app.mdx for building and installing; architecture/android.md for how it works
The in-sandbox agent	architecture/agent.mdx for shipped behavior; architecture/agent-plan.mdx for what is planned. Move parts that ship from the plan to the shipped page.

A new page in guides/, architecture/ or contributing/ shows up in the sidebar on its own; set sidebar.order in its frontmatter. Pages in start/ are listed in astro.config.mjs.

Style

• Describe what the product does today. Mark plans clearly as planned.
• Use the labels the UI shows, in bold: Settings → Integrations.
• Lead with the task. Put reference detail in tables.
• Link to other pages with root-relative links, such as /guides/threads/.

Update the agent diagram

1. Open /agent/ on the docs site. It loads architecture.excalidraw in Excalidraw.
2. Edit it, then Save to disk over docs/public/agent/architecture.excalidraw.
3. Export image → SVG with the background on, and save it as docs/public/agent/architecture.svg, which the docs page shows.