sections reference

Reference

Active contributors: Andy Taylor, Eno Reyes

Purpose

docs/reference/ collects the dense, lookup-oriented pages: the full CLI reference, the hooks reference (event schemas), and the two public APIs (analytics, readiness reports). These are the pages users open in a second tab while doing other work.

Directory layout

docs/reference/
├── cli-reference.mdx          # Full droid CLI reference
├── hooks-reference.mdx        # Hook events, payloads, return contracts
├── analytics-api.mdx          # Analytics API (~21 KB)
└── readiness-reports-api.mdx  # Readiness Reports API

In addition, the docs site has an API Reference tab in docs/docs.json that points at the live OpenAPI spec at https://api.factory.ai/api/v0/openapi.json (Mintlify renders it in-place).

Pages

CLI reference (cli-reference.mdx)

The single canonical reference for the droid binary. Lists every flag, every slash command, every keyboard shortcut. High churn — gets edited on most CLI releases. Often paired with an edit to docs/changelog/release-notes.mdx.

Hooks reference (hooks-reference.mdx)

One of the two longest reference pages (~26 KB). Documents:

• Hook event types and when they fire
• Payload schemas for each event
• Return contracts (what a hook may return, and how it affects the surrounding loop)
• Examples per event

Pair with docs/cli/configuration/hooks-guide.mdx for the how-to and docs/guides/hooks/*.mdx for recipes.

Analytics API (analytics-api.mdx)

The largest reference page (~21 KB). Documents the analytics surface customers can hit programmatically — used by enterprise teams to feed Factory usage data into their own dashboards. Cross-links to docs/enterprise/usage-cost-and-analytics.mdx and docs/enterprise/telemetry-export.mdx.

Readiness reports API (readiness-reports-api.mdx)

Programmatic access to agent readiness data. The "user-facing" side of agent readiness is at docs/web/agent-readiness/dashboard.mdx; the CLI side is at docs/cli/features/readiness-report.mdx. This page exposes the same data via a stable API.

Live API reference

The "API Reference" tab in docs/docs.json is configured as:

{
  "tab": "API Reference",
  "openapi": "https://api.factory.ai/api/v0/openapi.json"
}

Mintlify fetches the OpenAPI spec at build time and renders endpoint pages automatically. There is no .mdx source for these endpoint pages in this repo — the source of truth is the running API. A second openapi entry exists for the JP tab (jp/api-reference directory), so the same OpenAPI spec is rendered under Japanese localization.

Key source files

File	Purpose
docs/reference/cli-reference.mdx	Authoritative CLI flag/command reference
docs/reference/hooks-reference.mdx	Hook events, payloads, return contracts
docs/reference/analytics-api.mdx	Analytics API endpoints, auth, pagination, schemas
docs/reference/readiness-reports-api.mdx	Readiness report endpoints

Integration points

• CLI reference is the destination for every "see CLI Reference for…" link in docs/cli/getting-started/* and docs/cli/configuration/*.
• Hook reference + docs/cli/configuration/hooks-guide.mdx + docs/guides/hooks/* form a 3-page pattern (concept / reference / recipes).
• Analytics & readiness APIs are referenced from the corresponding enterprise and web docs.
• The OpenAPI tab is a separate live surface at https://api.factory.ai.

Entry points for modification

• Adding a new flag/command → update docs/reference/cli-reference.mdx and docs/changelog/release-notes.mdx together.
• Adding a new hook event → update both docs/reference/hooks-reference.mdx and docs/cli/configuration/hooks-guide.mdx. If a recipe is warranted, add docs/guides/hooks/<recipe>.mdx.
• API changes → the live OpenAPI tab updates automatically when the spec changes; the analytics/readiness MDX pages need manual edits when new endpoints are added.