API Documentation — Agent Guide

Document-driven API design for the ScalePad AMM v2 API. This directory contains the canonical API design docs, endpoint references, and an agent suite for automating documentation workflows.

Scope

Changes from agents working here should stay within:

• docs/api/ — design guidelines, domain docs, and open questions
• apps/api-docs/ — Docusaurus site and sidebars.ts

Do not modify backend source code, OpenAPI generation, or frontend consumers from this context.

Key Files

File	Purpose
docs/api/design-guidelines.md	Source of truth for all API design decisions
docs/api/open-questions.md	Pending design decisions
docs/api/index.md	API reference landing page and domain index
apps/api-docs/sidebars.ts	Sidebar navigation configuration
services/amm/agent-web-api/openapi.json	Live OpenAPI specification (read-only from this context)

Documentation Agents

A full agent suite lives in .ai/agents/. Start with these:

• .ai/agents/README.md — agent inventory, invocation examples, and how to add new agents
• .ai/agents/WORKFLOWS.md — day-to-day workflows: design-only, write, review, audit, ship

Quick reference

I want to...	Agent
Design endpoints for a new feature	doc-designer
Write docs from an approved design	doc-writer
Review docs for guideline compliance	doc-reviewer
Fix broken links or review findings	doc-fixer
Update the sidebar	sidebar-syncer
Check if docs are stale vs the OpenAPI spec	openapi-doc-syncer
Clean up a fully implemented proposal	proposal-cleaner
Full feature → reviewed docs	design-and-document
Audit all docs against the live spec	doc-audit
Feature → docs → committed PR	doc-ship

Directory Structure

docs/api/
├── design-guidelines.md    ← design rules (embedding, DTOs, response shapes, etc.)
├── open-questions.md       ← unresolved design decisions
├── index.md                ← API reference landing page
├── {domain}/               ← per-domain endpoint docs (apps/, users/, devices/, etc.)
│   ├── index.md            ← domain overview
│   └── {endpoint}.md       ← individual endpoint doc
└── .ai/agents/             ← agent definitions and playbooks