Add internal product docs

docs-internal/product/business-problem.md

@@ -0,0 +1,25 @@
+# The Problem Fabro Solves
+
+Fabro exists for teams that have outgrown the prompt-act-review loop used by most AI coding tools.
+
+## Why that loop breaks
+
+Interactive agent sessions work for small tasks, but they do not define a repeatable software process. In practice this creates four recurring problems:
+
+- The engineer must supervise the agent instead of defining the process once and reusing it.
+- There is no reliable gate between "the agent stopped" and "the work is ready."
+- Model choice is hard to control per step, so cost and quality drift.
+- Sessions are hard to resume, audit, and improve over time.
+
+## What Fabro adds
+
+Fabro treats the process itself as code:
+
+- Workflow graphs define stages, branching, loops, parallelism, and human gates.
+- Model stylesheets route different stages to different models and providers.
+- Sandboxes and Git checkpoints make runs isolated, resumable, and inspectable.
+- Event logs, verifications, and retros create a feedback loop after execution.
+
+## Product direction
+
+Fabro should optimize for trust in long-running workflows, not for chat UX. The product is most useful when expert engineers can design, run, inspect, and improve processes with minimal supervision.

docs-internal/product/current-state.md

@@ -0,0 +1,26 @@
+# Fabro Current State
+
+This snapshot is intentionally brief and omits volatile counts, benchmarks, and release metrics.
+
+## Public product shape
+
+Fabro currently presents as:
+
+- a CLI for defining and running workflows
+- an API server via `fabro serve`
+- a React web app for monitoring runs and inspecting workflows
+- a docs site and example workflows
+
+## Core capabilities documented today
+
+- Graphviz DOT workflows with agent, prompt, command, conditional, human, and parallel stages
+- CSS-like model stylesheets for per-stage model routing
+- sandboxed execution across local, Docker, Daytona, SSH, and other providers
+- Git checkpointing for resume, rewind, fork, and auditability
+- structured run artifacts and event streams for observability
+- verifications and insights in the broader product surface
+- retrospectives, documented as experimental
+
+## Current positioning
+
+Fabro is positioned as an open-source, self-hosted workflow orchestration layer for expert engineers. It is not positioned as an IDE plugin, autocomplete tool, or chat-first coding assistant.

docs-internal/product/personas.md

@@ -0,0 +1,20 @@
+# Fabro Personas
+
+Fabro is for expert engineers who want to encode software processes as workflows.
+
+## Primary users
+
+- **Solo expert engineer**: runs workflows locally to automate planning, implementation, testing, and review loops.
+- **Tech lead or platform engineer**: defines shared workflows, model routing rules, and quality gates for a team.
+- **Infrastructure engineer**: deploys `fabro serve`, configures sandboxes and auth, and keeps the system reliable.
+
+## Good fits
+
+- small teams comfortable with Git, CLIs, and source-controlled workflow files
+- teams that want repeatable automations such as PR review, test generation, or docs sync
+
+## Not a fit
+
+- beginners looking for guided product education
+- non-technical or no-code users
+- users mainly seeking IDE autocomplete or a chat-first coding assistant

docs-internal/product/product-description.md

@@ -0,0 +1,25 @@
+# Fabro Product Description
+
+Fabro is an open-source workflow orchestration platform for AI coding agents. Instead of treating software work as a chat session, Fabro lets you define the process as a Graphviz workflow and run it repeatedly.
+
+## What a workflow can contain
+
+A workflow can combine:
+
+- agent stages
+- prompt stages
+- shell commands
+- conditionals
+- human gates
+- parallel branches
+
+## What supports execution
+
+- model stylesheets choose models and providers per stage
+- sandboxes isolate execution from the host
+- Git checkpoints make runs resumable and auditable
+- event logs, verifications, and optional retros help teams inspect outcomes
+
+## Interfaces
+
+Fabro is CLI-first, with an API server and React web app for longer-running and shared workflows.

docs-internal/product/success-metrics.md

@@ -0,0 +1,26 @@
+# Fabro Success Metrics
+
+For product work, measure trust and useful outcomes, not just command execution.
+
+## Signals available now
+
+- CLI telemetry for command success and failure
+- per-run event streams in `progress.jsonl`
+- run artifacts such as `checkpoint.json`, `conclusion.json`, and verification data
+- `retro.json` when retros are enabled
+- API and web data for runs, workflows, usage, verifications, and insights
+
+## Metrics that matter most
+
+- successful outcomes per workflow type
+- cost and duration per successful outcome
+- verification pass rate
+- retry, loop, and human-intervention rate
+- resume, rewind, and fork usage
+
+## Current gaps
+
+- command success is not the same as product success
+- install, activation, and retention metrics are weak
+- some aggregate usage is server-local and resets on restart
+- cross-run comparison is still immature

docs-internal/product/technical-requirements.md

@@ -0,0 +1,24 @@
+# Fabro Technical Requirements
+
+This note captures stable constraints that product changes should respect.
+
+## Core constraints
+
+- Fabro ships primarily as a single Rust binary with CLI and server modes.
+- Workflows are defined in Graphviz DOT and should remain reviewable as source files.
+- The workflow engine must support loops, branching, parallel stages, commands, agent stages, and human gates.
+- Model routing is per-stage and provider-agnostic through stylesheets and config.
+- Execution happens through sandbox providers rather than assuming direct host access.
+- Git checkpointing is central to resume, rewind, fork, and auditability.
+- Runs produce structured artifacts such as `progress.jsonl`, `live.json`, `checkpoint.json`, and optional `retro.json`.
+- The HTTP API is OpenAPI-based, and the web app depends on that contract.
+
+## Operational constraints
+
+- Documented targets are macOS arm64, Linux x86_64, and Linux arm64.
+- Git is required for checkpointing-related workflows.
+- Docker, Graphviz, and SSH are optional system dependencies depending on the features in use.
+
+## Design bias
+
+Prefer changes that improve determinism, observability, resumability, and safe unattended execution. Avoid features that only make sense as IDE autocomplete or a chat-first REPL.