From dcb0166642f04a83cef07df222390723b2dde4d7 Mon Sep 17 00:00:00 2001 From: Giovanni Giovanni Date: Wed, 22 Jul 2026 04:55:31 -0400 Subject: [PATCH] docs(factory): reframe public copy as the AFI strategy workshop MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README leads with plain-language product framing ("AFI Factory is the strategy workshop for Agentic Financial Intelligence"): strategies, signals, analysis/agent workflows, playbook — before governance/implementation detail. - Add "What Factory is / is not" and "The Factory CLI is not a trading terminal"; reframe the agent section as "Connect an agent (MCP)" with a plain-English example. Exact CLI/MCP commands unchanged. - Persona docs (quant/operator/plugin-developer) lead with audience language; keep exact commands and technical detail. - Add docs/afi-city-copy.md handoff block (Factory landmark copy + CTAs). - Public examples avoid froggy/artifact/hash wording (AFI scoring template, verifiable workflow fingerprint); exact names retained in technical sections. Docs-only; no code, symbols, or behavior changed. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 102 +++++++++++++++++++++++----- docs/afi-city-copy.md | 55 +++++++++++++++ docs/onboarding/operator.md | 10 +-- docs/onboarding/plugin-developer.md | 8 ++- docs/onboarding/quant-authoring.md | 18 +++-- 5 files changed, 165 insertions(+), 28 deletions(-) create mode 100644 docs/afi-city-copy.md diff --git a/README.md b/README.md index 35eb43a..b45161b 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,70 @@ -# afi-factory +# AFI Factory -The AFI **pipeline authoring system** — the replaceable authoring implementation of -the analyst-configurable pipelines program (SLOT-FCP-FACTORY, authorized by -`afi-governance/decisions/factory-configurable-pipelines-v1.md`, D-FCP-4). +**AFI Factory is the strategy workshop for Agentic Financial Intelligence.** -## What Factory does +Factory helps traders, quants, builders, and agents turn market ideas into +repeatable **AFI-powered workflows** — deciding what signals to watch, what +analysis to run, how scoring should apply, and how the workflow connects into +AFI. Factory prepares the **playbook**; it does not trade, and it does not score. + +**Where Factory sits in AFI:** + +- **Factory** builds the playbooks — the strategy and agent workflows. +- **Machine** scores the signals. +- **Gateway** provides protocol access. +- **MCP** connects agents. +- **BUY SELL TERMINAL**, if and when built, is the trader-facing cockpit. + +**You work with Factory through three surfaces**, all backed by one authoring +engine: + +- a **local CLI** — for advanced users and operators to create, check, and + prepare strategy workflows; +- an **MCP interface** — so an agent can help design, check, and prepare those + workflows; +- a **TypeScript library** — to build on the same authoring functions directly. + +> **Under the hood** — Factory is the analyst-configurable pipeline *authoring* +> implementation (SLOT-FCP-FACTORY, authorized by +> `afi-governance/decisions/factory-configurable-pipelines-v1.md`, D-FCP-4). The +> contract-level mechanics — pipeline manifests, canonical hashing, and the typed +> operation layer — are documented in the technical sections below and remain exact. + +## What Factory is / is not + +**Factory is:** + +- a **strategy-workflow authoring surface** — define what a strategy watches, + what analysis runs, and how scoring applies; +- a **local CLI** for preparing and checking AFI workflows; +- an **agent-facing MCP surface** for designing and validating workflows; +- a **developer-accessible TypeScript library**. + +**Factory is not:** + +- a trading terminal or trade-execution system; +- the scoring engine — that is **Machine**; +- the protocol gateway — that is **Gateway**; +- a hosted web app or visual editor; +- a wallet, rewards, or settlement surface. + +Factory prepares the playbook; other AFI surfaces run it. + +## The Factory CLI is not a trading terminal + +The `afi-factory` CLI is an **authoring** tool. It creates, checks, and prepares +AFI strategy workflows — it never places an order, connects to a broker, moves a +position, or runs a live strategy. + +A trader-facing cockpit — **BUY SELL TERMINAL** or another future app — is a +separate surface built for traders. A trader may act through such a terminal, a +web app, or an agent, while Factory works behind the scenes to prepare the +workflow those surfaces rely on. + +Factory prepares the playbook; the terminal (when it exists) is where a trader +acts on it. + +## Authoring capabilities - **Template authoring + instantiation** — author `afi.pipeline-template.v1` documents with `{"$param":""}` value slots; instantiate them (defaults @@ -28,16 +88,25 @@ the analyst-configurable pipelines program (SLOT-FCP-FACTORY, authorized by - **Plugin scaffolding** — `afi.analysis-plugin.v1` manifest skeletons plus a TypeScript implementation-contract stub. -## Agent capability layer - -Every authoring capability above is also exposed to agents through **one -implementation-backed operation registry** (`src/operations/`). The TypeScript -SDK, the `afi-factory` CLI, the machine-readable capability catalog, the generic -agent-tool definitions, and the MCP adapter are all **projections over the same -typed operation handlers** — a capability cannot exist without a real handler, -a validated input schema, a validated output schema, a declared filesystem/ -security policy, and test coverage. Changing or removing an operation changes -every projection. +## Connect an agent (MCP) + +**Connect an agent to Factory so it can help design, check, and prepare +AFI-powered strategy workflows.** For example: a quant tells their agent *"draft +a momentum strategy that watches 15-minute candles, add a sentiment check, and +score it with an AFI scoring template."* The agent uses Factory's tools to draft +and assemble the workflow, validate it against the available analysis steps, +inspect the execution graph, and give it a verifiable workflow fingerprint — +without a person hand-writing a manifest. Factory only *authors and checks*; the +agent never trades or scores through it. + +Under the hood, every authoring capability above is exposed to agents through +**one implementation-backed operation registry** (`src/operations/`). The +TypeScript library, the `afi-factory` CLI, the machine-readable capability +catalog, the generic agent-tool definitions, and the MCP interface are all +**projections over the same typed operation handlers** — a capability cannot +exist without a real handler, a validated input schema, a validated output +schema, a declared filesystem/security policy, and test coverage. Changing or +removing an operation changes every projection. - **Machine-readable capability discovery** — `afi-factory capabilities --json` emits a deterministic catalog (stable id-sorted order, no timestamps/paths/ @@ -226,10 +295,11 @@ fixtures exercised by the test suite. ## Persona docs -- [Quant: authoring a strategy pipeline](docs/onboarding/quant-authoring.md) +- [Quant: authoring a strategy workflow](docs/onboarding/quant-authoring.md) - [Plugin developer](docs/onboarding/plugin-developer.md) - [Provider binding](docs/onboarding/provider-binding.md) - [Operator: installing and running validation](docs/onboarding/operator.md) +- [AFI City — Factory landmark copy (handoff)](docs/afi-city-copy.md) ## License diff --git a/docs/afi-city-copy.md b/docs/afi-city-copy.md new file mode 100644 index 0000000..a96e56f --- /dev/null +++ b/docs/afi-city-copy.md @@ -0,0 +1,55 @@ +# AFI City — Factory landmark copy (handoff) + +A reusable, plain-language copy block for the **Factory** landmark in AFI City. +This is the product-framing source of truth for public surfaces; keep it in sync +with the top of this repo's [README](../README.md). It intentionally leads with +finance-first language and avoids implementation terms (artifact, registry, +composition hash, pipeline artifact, scaffold, package). + +--- + +**Title** + +> Factory + +**Subtitle** + +> Design AFI-powered strategies and agent workflows. + +**Description** + +> Factory is AFI's strategy workshop — where traders, quants, builders, and +> agents turn market ideas into repeatable workflows that can plug into AFI's +> scoring, proof, and protocol-access layers. + +**Tagline** + +> Factory builds the playbooks. Machine scores the signals. + +**Recommended CTAs** + +- **Build with Factory** — points to the [README](../README.md). +- **Connect an Agent** — points to the "Connect an agent (MCP)" section of the README. +- **Source** — secondary/developer link to the GitHub repository. + +**Do not use** + +- **Launch Factory** — there is no hosted UI or web app to launch. +- **Submit a strategy through GitHub** — Factory is an authoring surface, not an intake. +- **Operation Catalog** — only if a rendered public catalog page actually exists. + +--- + +## Framing guardrails (keep copy accurate) + +Factory **does**: help define, validate, and prepare AFI-powered strategy and +agent workflows (locally via the CLI, for agents via MCP, for developers via the +library), and provide templates/examples/starters. + +Factory **does not**: execute trades, act as a trading terminal, score signals +itself, run provider execution, run the full AFI protocol, build or persist +evidence, or replace Gateway, Machine, Vault, or BUY SELL TERMINAL. + +Where Factory sits: **Factory** builds the playbooks · **Machine** scores the +signals · **Gateway** provides protocol access · **MCP** connects agents · +**BUY SELL TERMINAL** (if/when built) is the trader-facing cockpit. diff --git a/docs/onboarding/operator.md b/docs/onboarding/operator.md index cb4911d..d01114b 100644 --- a/docs/onboarding/operator.md +++ b/docs/onboarding/operator.md @@ -1,8 +1,10 @@ # Operator onboarding — installing and running validation -You are installing afi-factory to validate composition artifacts (CI gates, -registry review, pre-deployment checks). Factory executes nothing and needs -no services, no credentials, and no sibling checkouts. +You are installing Factory to **validate and prepare AFI strategy workflows** — +CI gates, registry review, pre-registration checks. Factory executes nothing and +needs no services, no credentials, and no sibling checkouts. (Under the hood the +things you validate are composition manifests, analyst-configs, and plugin sets; +the commands below are exact.) ## Install @@ -38,7 +40,7 @@ codes over any summary text. ## What capabilities mean for you Plugin manifests declare **requirement classes** the runtime environment must -satisfy. The official froggy set's five category-lane plugins each declare +satisfy. The official composition's five category-lane plugins each declare `provider:instance-backed`: the concrete provider is selected per lane by the manifest's explicit `providerInstanceRef` (the committed refs form the all-five keyless/self-hosted reference profile; the `aiMl` lane pins the diff --git a/docs/onboarding/plugin-developer.md b/docs/onboarding/plugin-developer.md index e895eb0..e4c1952 100644 --- a/docs/onboarding/plugin-developer.md +++ b/docs/onboarding/plugin-developer.md @@ -1,8 +1,10 @@ # Plugin developer onboarding -You are declaring (and separately implementing) one analysis plugin in the -seven governed categories: `technical`, `pattern`, `sentiment`, `news`, -`aiMl`, `merge`, `scorer`. +Plugins are the reusable **analysis and scoring building blocks** a strategy +workflow draws on — so this is the most technical persona. You are declaring +(and separately implementing) one analysis plugin in the seven governed +categories: `technical`, `pattern`, `sentiment`, `news`, `aiMl`, `merge`, +`scorer`. ## 1. Scaffold the manifest + contract stub diff --git a/docs/onboarding/quant-authoring.md b/docs/onboarding/quant-authoring.md index dc5d25c..1704383 100644 --- a/docs/onboarding/quant-authoring.md +++ b/docs/onboarding/quant-authoring.md @@ -1,7 +1,14 @@ -# Quant onboarding — authoring a strategy pipeline +# Quant onboarding — authoring a strategy workflow -You are composing **registered analysis plugins** into a scoring pipeline for -your strategy. You author *documents*; nothing here executes. +Factory is your **strategy workshop**. Here you turn a market idea into a +repeatable AFI **strategy workflow**: the signals it watches, the analysis it +runs, and how it's scored. You author *documents* that describe the workflow — +nothing here trades, executes, or scores. Once your workflow is registered, +**Machine** scores its signals (execution and trading happen on other AFI +surfaces). + +In technical terms you are composing **registered analysis plugins** into a +scoring pipeline; the steps below use the exact commands. ## 1. Start a project @@ -9,8 +16,9 @@ your strategy. You author *documents*; nothing here executes. npx afi-factory init my-strategy ``` -This scaffolds a template, its instantiated manifest, an analyst-config pinned -by canonical hash, and two plugin manifest skeletons. +This sets up a starter strategy workflow: a template, its instantiated manifest, +an analyst-config carrying a verifiable workflow fingerprint, and two plugin +skeletons. ## 2. Shape the graph