# Flowtend Docs

Flowtend Docs is the public guide map for product setup and agent automation. Operators should start with the overview path; agents should use the contract path directly.

## Operator Overview

- **Understand the product workflow first**: Read the getting-started guide for Project, Task, Validation, Review, and the difference between browser setup, CLI, and REST automation.
  Path: `/docs/getting-started`
  Link: [Read operator overview](/docs/getting-started)
- **Start from the browser path**: Use the hosted or local browser flow when a project owner needs the shortest path to the first task and Review packet.
  Path: `/docs/getting-started#quickstart`
  Link: [Open quickstart](/docs/getting-started#quickstart)
- **Choose CLI or REST deliberately**: Use the operator guide to decide whether the local CLI or project-scoped REST API is the right automation surface.
  Path: `/docs/getting-started#automation`
  Link: [Compare modes](/docs/getting-started#automation)

## Agent Contract

- **Open the public map**: Start with the public hub so operator and agent routes, raw files, and route contracts are visible.
  Path: `/docs`
  Link: [Open docs hub](/docs)
- **Use raw markdown when needed**: Fetch the markdown index directly when a crawler, agent, or text-only client cannot render the SPA route.
  Path: `/docs/index.md`
  Link: [Open raw index](/docs/index.md)
- **Use the agent contract**: Follow the live Flowtend automation contract for auth, project-scoped routes, worktree claims, and repo-work completion.
  Path: `/docs/skill-authoring`
  Link: [Open skill contract](/docs/skill-authoring)

## Agent Contract Invariants

- **Canonical hub**: `/docs`
  - Start here before opening deeper routes so current guide names and raw-file fallbacks stay aligned.
- **Text fallback**: `/docs/index.md`
  - Use this route when the client cannot render JavaScript or needs a crawlable index.
- **Automation route scope**: `/v1/projects/{project_id}/...`
  - Use only project-scoped API routes for live Flowtend automation.
- **Skill contract**: `/docs/skill-authoring`
  - Open this before creating or changing Codex or Claude Code Flowtend skills.

## Symphony-Aware Positioning

- **Symphony pattern**: `Runner and tracker orchestration`
  - OpenAI presents Symphony as an open-source Codex orchestration spec where a tracker such as Linear becomes the control plane and each open issue can get an agent workspace.
- **Flowtend role**: `Agent work system of record`
  - Flowtend owns the project board, workflow gates, project-scoped REST API, evidence history, and Review decisions that hosted or self-hosted runners can use.
- **Current boundary**: `No implied endorsement or adapter`
  - Flowtend can be positioned alongside Symphony-style runners, but it does not claim an official OpenAI partnership or a shipped Symphony adapter.

Source: [OpenAI Symphony article](https://openai.com/index/open-source-codex-orchestration-symphony/) - Use this source for Symphony-specific claims, then keep Flowtend claims limited to the shipped Flowtend board, Review, evidence, and API surfaces.

## Guide Map

- **Operator overview**: Project concepts, browser setup, local stack, and choosing between CLI and REST automation.
  Path: `/docs/getting-started`
  Link: [Read operator overview](/docs/getting-started)
- **Agent contract**: Runtime-native Flowtend skill rules for Codex, Claude Code, and live project API calls.
  Path: `/docs/skill-authoring`
  Link: [Read skill authoring](/docs/skill-authoring)

## Raw Files

- [Docs index markdown](/docs/index.md): MkDocs-style guide map for agents that fetch text instead of rendering JavaScript.

## Route Contracts

- `/docs`: Public docs hub with sidebar navigation and this-page anchors.
- `/docs/index.md`: Raw markdown index for non-JavaScript agents.
- `/docs/getting-started`: Product, local setup, CLI, and REST setup guide.
- `/docs/skill-authoring`: Rendered automation contract for Flowtend skills.

## Access Notes

- Treat /docs as the canonical public docs hub before opening a deeper contract page.
- Use /docs/index.md when the client needs a text-only map before opening rendered guide pages.
- Use only project-scoped Flowtend API routes under /v1/projects/{project_id}/... for live automation.
- Keep secrets out of skill files, logs, copied prompts, PR text, and normal output.