scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-08-28 05:27:41 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
fabro/docs/internal/product/technical-requirements.md
Bryan Helmkamp 671324a06f
docs(secrets): document settings-declared credentials, fix stale local-run guidance 
server-secrets-strategy.md described only two credential mechanisms — bootstrap
ServerSecrets and vault-only optional integrations — and stated its most
restrictive rule in terms of "server runtime", which is ambiguous now that every
run is a server process plus a worker. It omitted the third mechanism actually
used by operator-configured integrations: settings-declared credentials in
InterpString fields, resolved at consumption time from {{ env.NAME }} or
{{ secrets.NAME }}, as LLM provider extra_headers already does.

Add a "Which process resolves what" table keyed on resolving process and timing,
a "Settings-declared credentials" section with the extra_headers precedent, and a
mechanism table at the head of "Adding A New Server Secret". Replace "server
runtime" with per-process statements, and describe where CredentialResolver's
process-env fallback is actually live.

Also correct six docs that told operators to export provider keys for "standalone
local runs". There is no CLI-local run execution: runs always execute in a worker
whose environment is cleared and repopulated from WORKER_ENV_ALLOWLIST, which
excludes provider API keys. Those instructions could not have worked.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-25 09:04:59 -04:00

1.4 KiB
Raw Permalink Blame History

Fabro Technical Requirements

This note captures stable constraints that product changes should respect.

Core constraints

  • Fabro ships primarily as a single Rust binary providing both the CLI and the server.
  • Runs always execute in a server-managed worker process. There is no CLI-local run execution, so "CLI vs server" is a matter of which subcommand you invoked, not two execution 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 conclusion.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.