docs: define ECC platform value loop (#2119)

docs/architecture/cross-harness.md

@@ -15,6 +15,8 @@ Claude Code, Codex, OpenCode, Cursor, Gemini, and future harnesses should adapt
 
 For the operator-facing support matrix and scorecard workflow, see
 [Harness Adapter Compliance Matrix](harness-adapter-compliance.md).
+For the full-stack platform framing and product-integration loop, see
+[ECC Platform Value Loop](platform-value-loop.md).
 
 ## Portability Model
 
@@ -118,6 +120,8 @@ Still maturing:
 - release packaging for `ecc2/`
 - cross-harness session resume semantics
 - deeper memory and operator planning layers
+- the full platform loop where external products contribute skill packs,
+  gated APIs, evals, and case studies back into ECC
 
 ## Rule For New Work
 

docs/architecture/platform-value-loop.md

@@ -0,0 +1,120 @@
+# ECC Platform Value Loop
+
+ECC 2.0 is moving from a portable harness layer toward a full operator
+system. The product direction is three layers:
+
+1. Meta-harness: portable skills, rules, hooks, MCP conventions, release gates,
+   evals, and security evidence.
+2. Dedicated ECC agent: an agent that directly operates over ECC assets instead
+   of only reading them as static instructions.
+3. Control pane / agentic IDE: a visible operator surface for sessions, queues,
+   skills, memory, evidence, releases, and team workflows.
+
+The control pane is still a release-candidate direction until it is backed by a
+reproducible demo. The public claim is:
+
+```text
+ECC can be used full-stack as a meta-harness + agent + control pane, or
+selectively as the portable harness layer inside the AI coding tools teams
+already use.
+```
+
+## OSS Platform Thesis
+
+The older open-source infrastructure playbook was distribution first: free
+source and generous self-serve access created the default developer vocabulary,
+then hosted infrastructure, managed teams, support, and enterprise features
+captured value. Databases, app platforms, and edge platforms made this obvious:
+developers adopted the free surface, teams standardized on the brand, and the
+paid product made the workflow easier to run at scale.
+
+AI-agent infrastructure should follow the same shape, but the hosted value is
+not just deployment. The paid or managed surface is:
+
+- team memory and session routing;
+- observable queues, handoffs, and agent runs;
+- managed evals, release gates, and evidence packs;
+- security review, supply-chain findings, and policy enforcement;
+- billing, entitlement, sponsor, and partner workflows;
+- product-specific integrations that can become reusable ECC skills.
+
+The open repo stays useful on its own. The platform earns value when serious
+teams want the same workflows managed, measured, secured, or connected to their
+own products.
+
+## Product Integration Contract
+
+External products can build on ECC without becoming ECC-branded products. The
+contract is:
+
+| Layer | Product contributes | ECC receives |
+| --- | --- | --- |
+| Skill pack | Public, non-secret workflows in `skills/*/SKILL.md` | New reusable agent behavior and install surface |
+| Gated API | Optional product credentials such as `PRODUCT_API_KEY` | A clear upgrade/request path without leaking secrets |
+| Fixtures and docs | Sanitized examples, no private accounts or live keys | Testable public proof instead of claims |
+| Eval and risk gates | Advice, safety, data, and execution boundaries | Reusable release discipline and trust surface |
+| Case study | A real product workflow that works through ECC | Distribution, sponsors, Pro interest, consulting demand |
+
+Every integration needs:
+
+- a public workflow that works without private credentials;
+- a separate gated path for live product data or actions;
+- a clear business boundary so billing and ownership are not blurred;
+- tests or documented commands proving the integration surface;
+- a support route that does not require public secrets or private account data.
+
+## Ito Example
+
+Ito is a separate prediction-market basket product. ECC can still distribute
+Ito-shaped skills because the skill workflows are useful without making ECC
+Tools an Ito product.
+
+The safe public surface is:
+
+- research market, underlier, venue, and liquidity context;
+- compare baskets against a user's own notes, portfolio constraints, or thesis;
+- draft non-advisory trade-planning worksheets for manual review;
+- visualize market/concept relationships and backtesting outputs when data is
+  available;
+- use prediction-market signals as one input into broader agent research.
+
+The gated surface is:
+
+- live Ito basket data;
+- account-specific state;
+- API-backed backtesting or visualization;
+- any workflow requiring `ITO_API_KEY`.
+
+The boundary is strict: public ECC skills do not place trades, do not provide investment advice, do not expose private strategy, and do not merge ECC Tools billing with Ito billing.
+
+## Value Loop
+
+The platform loop should be explicit:
+
+1. A product team builds a useful workflow as an ECC skill pack.
+2. The public skill pack works with public sources or local user-provided data.
+3. Serious users request gated access for live product data or hosted features.
+4. Product usage produces new operator patterns, failure modes, and examples.
+5. Sanitized patterns become better ECC skills, evals, gates, or docs.
+6. ECC gains distribution, maintainers, sponsors, Pro interest, and consulting leads.
+7. The product gains adoption because agent users can operate it through an
+   already-installed harness.
+
+This is different from enterprise consulting alone. Consulting can fund the
+work, but the platform goal is repeatable distribution: every useful product
+integration becomes another reason to install ECC, and every serious ECC user
+becomes a possible sponsor, Pro user, partner, or integration customer.
+
+## Release Lane
+
+Keep release claims separated:
+
+- `1.10.1`: stable reliability and docs patch for released users.
+- `1.11.0`: public OSS workflow-catalog momentum that does not require the
+  control pane to be GA.
+- `2.0.0-rc.x`: control-pane, dedicated-agent, platform, and release-evidence
+  work while the full operator system remains prerelease.
+
+Do not announce ORCA/CONDUCTOR-grade parity, marketplace billing, official
+plugin-directory listing, live trading, or native-payments readiness without
+fresh evidence and owner approval.

docs/releases/2.0.0-rc.1/ito-prediction-market-skill-pack.md

@@ -51,6 +51,9 @@ not place trades. They can help a user:
 
 ## Growth Loop
 
+For the general product-integration contract, see
+[`docs/architecture/platform-value-loop.md`](../../architecture/platform-value-loop.md).
+
 The loop is intentionally simple:
 
 1. ECC users discover useful public prediction-market skills.

docs/releases/2.0.0-rc.1/preview-pack-manifest.md

@@ -14,6 +14,7 @@ tagging plugin surfaces, uploading video, or posting announcements.
 | `skills/hermes-imports/SKILL.md` | Sanitized Hermes-to-ECC import workflow | Includes import rules, sanitization checklist, conversion pattern, and output contract |
 | `docs/architecture/cross-harness.md` | Shared substrate model for Claude Code, Codex, OpenCode, Cursor, Gemini, Hermes, and terminal-only use | Names portability boundaries and does not claim unsupported native parity |
 | `docs/architecture/harness-adapter-compliance.md` | Adapter matrix and scorecard | Verified by `npm run harness:adapters -- --check` |
+| `docs/architecture/platform-value-loop.md` | Product integration and full-stack platform thesis | Keeps external product skill packs, gated APIs, case studies, sponsorship, Pro, and consulting loops separate from unsupported GA/control-pane claims |
 | `docs/architecture/observability-readiness.md` | Local operator-readiness gate | Verified by `npm run observability:ready` |
 | `docs/architecture/progress-sync-contract.md` | GitHub, Linear, handoff, roadmap, and work-item sync boundary | Checked by `node scripts/platform-audit.js --json` |
 | `scripts/preview-pack-smoke.js` | Deterministic preview-pack smoke gate | Verified by `npm run preview-pack:smoke` |
@@ -46,6 +47,11 @@ tagging plugin surfaces, uploading video, or posting announcements.
 
 ## Itô Skill Pack Boundary
 
+The general product-integration contract is recorded in
+`docs/architecture/platform-value-loop.md`. The Itô pack is the first worked
+example: useful public workflows, separate gated API access, and sanitized
+operator patterns feeding back into ECC without merging business ownership.
+
 The preview pack includes six public teaser skills for prediction-market and
 Itô-adjacent workflows:
 

docs/releases/2.0.0/ecc-2-hypergrowth-release-command-center.md

@@ -66,6 +66,27 @@ The operating rhythm after launch should be weekly:
 5. one measurable funnel readback covering repo traffic, sponsor clicks, Pro
    conversions, MRR movement, and inbound replies.
 
+## Platform Value Loop
+
+The long-term platform thesis is recorded in
+[`docs/architecture/platform-value-loop.md`](../../architecture/platform-value-loop.md).
+ECC should stay useful as free OSS while the managed value accrues around team
+memory, observable sessions, release gates, evals, security evidence, hosted
+analysis, billing, partner workflows, and product-specific integrations.
+
+Product integrations should behave like repeatable distribution loops:
+
+1. ship a public skill pack that works without private credentials;
+2. keep live product data or actions behind an explicit gated API path;
+3. add fixtures, docs, evals, and risk gates so the workflow is testable;
+4. convert sanitized product usage back into ECC skills, docs, or evidence;
+5. route serious teams toward sponsors, Pro, partners, or consulting.
+
+Itô is the current example: prediction-market research, basket comparison,
+manual non-advisory planning, and data-atlas workflows can be distributed
+through ECC, while live Itô data and account-specific calls remain gated by
+`ITO_API_KEY` and separate from ECC Tools billing.
+
 ## Release Gates
 
 | Lane | Done when | Current action |

tests/docs/platform-value-loop.test.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed++;
+  } catch (error) {
+    console.log(`  ✗ ${name}`);
+    console.log(`    Error: ${error.message}`);
+    failed++;
+  }
+}
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
+}
+
+console.log('\n=== Testing ECC platform value loop docs ===\n');
+
+test('platform value loop doc defines the three-layer ECC 2.0 direction', () => {
+  const source = read('docs/architecture/platform-value-loop.md');
+
+  for (const marker of [
+    'Meta-harness',
+    'Dedicated ECC agent',
+    'Control pane / agentic IDE',
+    'reproducible demo',
+    'ECC can be used full-stack as a meta-harness + agent + control pane',
+  ]) {
+    assert.ok(source.includes(marker), `platform value loop doc missing ${marker}`);
+  }
+});
+
+test('platform value loop doc records the OSS-to-managed value thesis', () => {
+  const source = read('docs/architecture/platform-value-loop.md');
+
+  for (const marker of [
+    'open-source infrastructure playbook',
+    'team memory and session routing',
+    'managed evals, release gates, and evidence packs',
+    'security review, supply-chain findings, and policy enforcement',
+    'sponsors',
+    'Pro interest',
+    'consulting leads',
+  ]) {
+    assert.ok(source.includes(marker), `platform value loop doc missing value marker ${marker}`);
+  }
+});
+
+test('product integration contract keeps external products useful but separate', () => {
+  const source = read('docs/architecture/platform-value-loop.md');
+
+  for (const marker of [
+    'Skill pack',
+    'Gated API',
+    'Fixtures and docs',
+    'Eval and risk gates',
+    'Case study',
+    'a public workflow that works without private credentials',
+    'a separate gated path for live product data or actions',
+    'a clear business boundary so billing and ownership are not blurred',
+  ]) {
+    assert.ok(source.includes(marker), `platform value loop doc missing contract marker ${marker}`);
+  }
+});
+
+test('Ito example preserves non-advisory and gated-access boundaries', () => {
+  const source = read('docs/architecture/platform-value-loop.md');
+
+  for (const marker of [
+    'Ito is a separate prediction-market basket product',
+    'visualize market/concept relationships and backtesting outputs',
+    'ITO_API_KEY',
+    'do not place trades',
+    'do not provide investment advice',
+    'do not merge ECC Tools billing with Ito billing',
+  ]) {
+    assert.ok(source.includes(marker), `platform value loop doc missing Ito boundary ${marker}`);
+  }
+});
+
+test('release docs link the platform value loop into the rc surface', () => {
+  const crossHarness = read('docs/architecture/cross-harness.md');
+  const previewManifest = read('docs/releases/2.0.0-rc.1/preview-pack-manifest.md');
+  const itoPack = read('docs/releases/2.0.0-rc.1/ito-prediction-market-skill-pack.md');
+  const hypergrowth = read('docs/releases/2.0.0/ecc-2-hypergrowth-release-command-center.md');
+
+  for (const source of [crossHarness, previewManifest, itoPack, hypergrowth]) {
+    assert.ok(
+      source.includes('platform-value-loop.md'),
+      'expected release/cross-harness surface to link platform-value-loop.md'
+    );
+  }
+
+  assert.ok(previewManifest.includes('Product integration and full-stack platform thesis'));
+  assert.ok(hypergrowth.includes('Product integrations should behave like repeatable distribution loops'));
+});
+
+test('platform value loop does not overclaim release status or trading ability', () => {
+  const source = read('docs/architecture/platform-value-loop.md');
+  const forbidden = [
+    'ORCA/CONDUCTOR-grade parity is live',
+    'control pane is GA',
+    'native-payments readiness is live',
+    'official plugin-directory listing is live',
+    'public ECC skills place trades',
+  ];
+
+  for (const phrase of forbidden) {
+    assert.ok(!source.includes(phrase), `platform value loop should not include overclaim: ${phrase}`);
+  }
+});
+
+if (failed > 0) {
+  console.log(`\nFailed: ${failed}`);
+  process.exit(1);
+}
+
+console.log(`\nPassed: ${passed}`);
+