diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..99f457a --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,65 @@ +name: Deploy MARGINAL website + +on: + push: + branches: ["main"] + paths: + - "site/**" + - "assets/marginal-readme-hero.png" + - "demos/killer-demo/**" + - ".github/workflows/pages.yml" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Configure Pages + uses: actions/configure-pages@v5 + - name: Assemble website + shell: bash + run: | + set -euo pipefail + rm -rf _site + mkdir -p _site/assets _site/demo + cp -R site/. _site/ + cp assets/marginal-readme-hero.png _site/assets/marginal-readme-hero.png + cp -R demos/killer-demo/. _site/demo/ + touch _site/.nojekyll + - name: Verify generated website + shell: bash + run: | + set -euo pipefail + test -f _site/index.html + test -f _site/styles.css + test -f _site/app.js + test -f _site/robots.txt + test -f _site/sitemap.xml + test -f _site/assets/marginal-readme-hero.png + test -f _site/demo/RESULTS.md + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: _site + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fcc882..c144e26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,7 +19,6 @@ All notable changes to MARGINAL are documented here. The project follows Semanti - provider-neutral `Outcome` contract separated from action-level realized gain; - schema-versioned `JsonlDecisionLedger` with strict envelope validation, run/task/trajectory/engine/model correlation, task/outcome consistency checks, and monotonic sequencing; - `PrivacyProfile` with `local_full`, keyed `safe_telemetry`, and separate `aggregate_export` modes; -- privacy-preserving aggregate export with a configurable minimum group size of five by default; - field classification for safe-by-default, pseudonymous, and potentially sensitive evidence; - HMAC-SHA-256 identifier pseudonymization, UTC-day timestamp generalization, strict free-text removal, and local 256-bit key management; - opaque random local identifier generation for runs, tasks, and other caller-defined namespaces; @@ -35,6 +34,11 @@ All notable changes to MARGINAL are documented here. The project follows Semanti ### Changed +- redesigned the repository README as a concise, SEO-oriented technical landing page; +- added a dependency-free, responsive, accessible GitHub Pages product website; +- consolidated the product website, hero asset, and Killer Demo into one Pages deployment; +- documented website ownership, deployment, accessibility, privacy, and evidence guardrails. + - `Decision` is backward compatible but now carries recommendation, mode, reason-code, uncertainty, confidence, and estimator metadata; - `MarginalPolicy` now has a stable identity and supports both versioned and legacy custom estimators; - `Treasury.summary()` includes mode, policy, estimator, observed overruns, failed settlements, outcomes, and estimator observations; diff --git a/MARGINAL-readme-github-pages.zip b/MARGINAL-readme-github-pages.zip new file mode 100644 index 0000000..f8032b1 Binary files /dev/null and b/MARGINAL-readme-github-pages.zip differ diff --git a/PACKAGE_MANIFEST.json b/PACKAGE_MANIFEST.json new file mode 100644 index 0000000..aa212ac --- /dev/null +++ b/PACKAGE_MANIFEST.json @@ -0,0 +1,22 @@ +{ + "package_type": "repository overlay", + "repository": "SignalLayerLabs/Marginal", + "generated_on": "2026-08-06", + "files": [ + ".github/workflows/pages.yml", + "CHANGELOG.md", + "README.md", + "VISUAL_STUDIO_COMMIT_PROMPT.md", + "docs/superpowers/plans/2026-08-06-readme-pages.md", + "docs/superpowers/specs/2026-08-06-readme-pages-design.md", + "docs/website.md", + "scripts/validate_readme_pages.py", + "site/404.html", + "site/app.js", + "site/index.html", + "site/robots.txt", + "site/sitemap.xml", + "site/styles.css" + ], + "important": "Ensure exactly one workflow invokes actions/deploy-pages." +} \ No newline at end of file diff --git a/README.md b/README.md index 3ac1078..032edf0 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,94 @@
-MARGINAL — Compute capital allocation for AI agents +MARGINAL — compute governance and token optimization for AI agents -
+# MARGINAL + +### Compute governance and token optimization for AI agents + +**MARGINAL helps AI agents decide whether the next model call, tool call, search, retry, review, or sub-agent is worth its compute cost.** + +Open source · Local first · Provider neutral · Zero mandatory runtime dependencies + +[Website](https://signallayerlabs.github.io/Marginal/) · +[Quickstart](docs/quickstart.md) · +[Architecture](docs/architecture.md) · +[Roadmap](ROADMAP.md) · +[Contributing](CONTRIBUTING.md) [![CI](https://github.com/SignalLayerLabs/Marginal/actions/workflows/ci.yml/badge.svg)](https://github.com/SignalLayerLabs/Marginal/actions/workflows/ci.yml) [![CodeQL](https://github.com/SignalLayerLabs/Marginal/actions/workflows/codeql.yml/badge.svg)](https://github.com/SignalLayerLabs/Marginal/actions/workflows/codeql.yml) [![Release](https://img.shields.io/github/v/release/SignalLayerLabs/Marginal?style=flat-square)](https://github.com/SignalLayerLabs/Marginal/releases) [![Python 3.10–3.13](https://img.shields.io/badge/python-3.10--3.13-blue.svg?style=flat-square)](https://www.python.org/) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg?style=flat-square)](LICENSE) -[![Zero runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen.svg?style=flat-square)](pyproject.toml) +[![Runtime dependencies: 0](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen.svg?style=flat-square)](pyproject.toml)
--- -MARGINAL is an open-source decision, accounting, and evidence layer for AI agents. It evaluates proposed model calls, tool calls, searches, retries, reviewers, and sub-agents before they run, then accounts for what actually happened. - -> **Hard budgets ask “can we afford this?” MARGINAL also asks “is this worth funding?”** - -Version `0.2.0` adds the **Learning Loop Foundation**: Shadow Mode, a versioned Decision Ledger, explicit privacy profiles, measured outcome contracts, versioned value estimators, policy replay, and a universal engine-neutral runtime for future Codex, Claude Code, GitHub Copilot, OpenCode, and other adapters. - -MARGINAL does not compress prompts or replace an agent framework. It can eliminate entire low-value actions before they consume tokens, or observe them without interference while evidence is collected. - -## Why this exists - -Agent runtimes commonly execute the next step because it appears in a workflow, a model requested it, or a hard limit has not yet been reached. Those mechanisms answer whether work is permitted; they do not compare the expected improvement of the next action with its total economic cost. +## Why MARGINAL -MARGINAL adds that allocation layer while keeping execution and evidence explicit: +Most agent runtimes ask: -- rank candidate actions by marginal value; -- reserve budget before execution and settle actual usage afterward; -- protect verification capacity; -- prevent concurrent double-spend and state-insensitive duplicates; -- observe recommendations without blocking through Shadow Mode; -- record versioned policy, estimator, cost, failure, and outcome evidence; -- protect quasi-identifiers and free text through explicit privacy profiles; -- support provider-neutral synchronous, asynchronous, and engine-adapter integrations; -- keep the runtime core free of mandatory dependencies. +> **Can this action run?** -## What changed in v0.2 +MARGINAL adds the economic question: -### Shadow Mode +> **Is this action worth funding now?** -Shadow Mode evaluates every proposed action but never blocks it: +It evaluates expected improvement against tokens, direct cost, latency, risk, remaining budget, verification reserves, and prior evidence. It then records what actually happened so future policies can be evaluated against real outcomes. ```text -agent proposes action - ↓ -MARGINAL recommends allow or deny - ↓ -action still executes - ↓ -actual cost and verified outcome are recorded +observe decisions + ↓ +measure actual cost and outcomes + ↓ +estimate marginal value + ↓ +allocate compute + ↓ +measure calibration and regret + ↓ +improve the policy ``` -This is the safe default for collecting evidence before enforcement. - -### Decision Ledger - -`JsonlDecisionLedger` records schema-versioned, append-only evidence with: - -- run, task, trajectory, engine, and model identity; -- policy and estimator versions; -- recommended versus applied decisions; -- estimated and actual costs; -- failures, overruns, observations, and outcomes; -- deterministic sequence numbers for replay and audit. - -Prompts and model outputs are not recorded by default. That alone is not sufficient for safe -sharing: task IDs, action names, model identity, repository metadata, verifier details, and -error text can still reveal sensitive information. - -### Privacy profiles - -Every Decision Ledger field is treated as safe-by-default, pseudonymous, or potentially -sensitive. MARGINAL provides three explicit profiles: - -- `LOCAL_FULL` preserves the complete operational ledger on a trusted local filesystem; -- `SAFE_TELEMETRY` removes free text and metadata, pseudonymizes identifiers with a local - HMAC-SHA-256 key, and generalizes exact timestamps; -- `generate_local_identifier(...)` creates opaque random local IDs when correlation with - external names is unnecessary; -- `AGGREGATE_EXPORT` creates grouped generalized rows with no identifiers or timestamps and - suppresses groups smaller than five records by default. - -`aggregate_export` is a separate export path, not an operational ledger mode. Its default -minimum group size is five and can be raised for more conservative sharing. Pseudonymization -is not anonymization; inspect data before sharing it. See [Privacy profiles](docs/privacy.md). - -### Versioned Value Estimator +The goal is not to make an agent merely cheaper. It is to make autonomous work **economically disciplined, measurable, and auditable**. -`ValueEstimator` now returns `ValueEstimate` objects with expected gain, uncertainty, confidence, sample size, provenance, and a stable estimator identity. Explicit caller estimates remain supported, and historical observations can be contextualized by engine, phase, task type, language, and model. +MARGINAL also supports Shadow Mode, where recommendations can be observed without blocking execution, letting teams collect evidence before enforcement. -MARGINAL does **not** infer that every action caused a successful task. Action-level realized gain must be supplied explicitly through `Treasury.observe_value(...)`. +## How it works -### Universal Agent Protocol +```text +Agent proposes an action + ↓ +MARGINAL estimates value and total cost + ↓ +ALLOW · DENY · RECOMMEND · SHADOW + ↓ +Budget is reserved before execution + ↓ +Actual usage and verified outcome are settled + ↓ +Versioned evidence is written to the Decision Ledger +``` -`AgentAction`, `AgentEvent`, `AgentDecision`, `AgentCapabilities`, and `UniversalRuntime` provide the shared contract for thin engine adapters. Engine-specific code translates native events; the economic policy remains in one core. +MARGINAL can sit around model calls, tool calls, searches, tests, reviewers, retries, and sub-agents. The core remains engine-neutral; thin adapters translate native events from coding agents into one universal protocol. -The versioned JSON contracts ship inside the installed package as well as in the repository: +## What makes it different -```python -from marginal import available_schemas, load_schema - -print(available_schemas()) -event_schema = load_schema("agent-event-v1.json") -``` +| Capability | What it adds | +|---|---| +| **Transactional accounting** | Atomic reserve, settle, abort, overrun, hierarchy, and verification reserves—not a token counter wrapper. | +| **Shadow-to-enforce lifecycle** | Observe recommendations safely before allowing the policy to block work. | +| **Learning Loop Foundation** | Versioned estimators, outcomes, replay, and evidence for progressively better allocation. | +| **Privacy by design** | Local ledgers, pseudonymous telemetry, aggregate exports, and no prompt/output logging by default. | +| **Universal agent protocol** | One core for Codex, Claude Code, GitHub Copilot, OpenCode, and future compatible runtimes. | +| **Scientific honesty** | Synthetic demonstrations are labeled as demonstrations; public claims require measured telemetry and preserved quality. | ## Install -Install the tagged GitHub release: +Install the tagged release: ```bash pip install "marginal-ai @ git+https://github.com/SignalLayerLabs/Marginal.git@v0.2.0" @@ -124,23 +102,22 @@ cd Marginal python -m pip install -e ".[dev]" ``` -## Five-minute enforced integration +## Quickstart ```python from marginal import Action, BudgetLimits, Cost, Treasury, budgeted_call, build_policy -policy = build_policy("balanced") treasury = Treasury( BudgetLimits( max_tokens=100_000, max_usd=2.00, verification_reserve_tokens=10_000, ), - policy=policy, + policy=build_policy("balanced"), mode="enforce", ) -response = budgeted_call( +result = budgeted_call( treasury, your_expensive_function, "input", @@ -153,136 +130,41 @@ response = budgeted_call( ) ``` -The wrapped function is never called when enforcement denies the action. Approved estimates are reserved immediately, preventing parallel actions from oversubscribing the same treasury. - -## Fund the best next action - -```python -allocation = treasury.fund_best( - [ - Action( - name="search the web", - kind="research", - cost=Cost(tokens=6_000, usd=0.06), - expected_gain=0.05, - ), - Action( - name="run the targeted test", - kind="verification", - cost=Cost(tokens=800, usd=0.002), - expected_gain=0.18, - is_verification=True, - ), - ] -) - -if allocation is not None: - result = funded_call(treasury, allocation, execute, allocation.action) -``` - -`fund_best` evaluates candidates against one locked state, records the full ranking, and reserves only the highest-value affordable candidate. It remains an active selection API in every execution mode. - -## Use measured provider usage - -```python -response = budgeted_call( - treasury, - client.responses.create, - action=action, - usage_extractor=extract_common_llm_usage, - model="YOUR_MODEL", - input="Draft the answer.", -) -``` - -The total-token extractor preserves direct USD, latency, and risk values that a provider response does not expose consistently. `extract_common_token_usage` provides the additive input, cached-input, non-reasoning output, reasoning, and total breakdown. +When enforcement denies the action, the wrapped function is not called. Approved estimates are reserved immediately, preventing concurrent actions from oversubscribing the same treasury. -Async callables use the same lifecycle: +Start with [`shadow` mode](docs/quickstart.md) when collecting evidence for a new workflow. -```python -response = await async_budgeted_call( - treasury, - client.responses.create, - action=action, - usage_extractor=extract_common_llm_usage, - **request, -) -``` +## Execution modes -## Start safely with Shadow Mode +| Mode | Applied behavior | Best for | +|---|---|---| +| `shadow` | Executes every proposed action and records the recommendation | Safe observation and calibration | +| `recommend` | Executes while surfacing the policy recommendation | Human or agent advisory workflows | +| `enforce` | Applies allow/deny and hard-budget decisions | Validated production control | -```python -from marginal import ( - Action, - BudgetLimits, - Cost, - DecisionLedgerContext, - JsonlDecisionLedger, - Treasury, - budgeted_call, - build_policy, -) +`fund_best(...)` remains an active selection API in every mode because the caller is explicitly asking MARGINAL to choose among alternatives. -ledger = JsonlDecisionLedger( - "marginal-ledger.jsonl", - context=DecisionLedgerContext( - run_id="run-001", - task_id="task-042", - trajectory_id="baseline-a", - engine="codex", - model="your-model", - ), - privacy_profile="safe_telemetry", - privacy_key_path=".marginal/privacy.key", -) +## The Learning Loop Foundation -treasury = Treasury( - BudgetLimits(max_tokens=50_000, verification_reserve_tokens=5_000), - policy=build_policy("quality-first"), - trace_sink=ledger, - mode="shadow", -) +MARGINAL v0.2 moves beyond manually supplied expected gain without pretending causal inference is already solved. -result = budgeted_call( - treasury, - your_expensive_function, - action=Action( - name="ask another reviewer", - kind="review", - cost=Cost(tokens=5_000), - expected_gain=0.01, - ), -) -``` +The current foundation provides: -Even when the policy recommendation is deny, Shadow Mode executes the callable, records the non-blocking override, and accounts for actual usage. +- versioned `ValueEstimator` identities and configurations; +- contextual observations by engine, phase, task type, language, and model; +- uncertainty, confidence, sample size, and provenance; +- task-level verified outcomes; +- separately supplied action-level realized gain; +- policy replay over recorded actions; +- deterministic Decision Ledger records for audit and comparison. -## Record verified outcomes and action-level learning +A successful task does **not** prove that every action in its trajectory caused success. MARGINAL keeps task outcomes and action attribution separate so correlation is not mislabeled as causal value. -```python -from marginal import Action, Outcome - -# Task outcome: evidence about the trajectory as a whole. -treasury.record_outcome( - Outcome( - task_id="task-042", - reward=1.0, - resolved=True, - verifier="pytest", - evidence={"suite": "tests/test_payment.py"}, - ) -) +Read [Learning and replay](docs/concepts.md) and [Benchmarking](docs/benchmarking.md). -# Action-level realized gain: supplied only when the application can justify it. -treasury.observe_value( - Action(name="run targeted test", kind="verification"), - realized_gain=0.18, -) -``` - -Task outcomes and action-level realized gain are deliberately separate. A passing task alone does not establish the causal value of every action in its trajectory. +## Universal Agent Runtime -## Universal runtime for engine adapters +The universal runtime gives engine adapters one shared contract: ```python from marginal import AgentAction, AgentCapabilities, Cost, UniversalRuntime @@ -311,282 +193,145 @@ decision = runtime.before_action( deduplication_scope="once_per_state", ) ) - -# The adapter applies the decision, executes when allowed, then settles actual usage. -runtime.after_action("read-1", actual_cost=Cost(tokens=6_400)) -``` - -`UniversalRuntime` in `enforce` mode requires an adapter that declares `block_actions=True`; MARGINAL refuses to advertise enforcement through an observe-only integration. - -Protocol v1 defines `allow`, `deny`, `modify`, `defer`, `reuse`, `stop`, and `force_verify` directives so adapters can negotiate future control surfaces consistently. The v0.2 reference runtime currently derives `allow` and `deny` from the core decision; richer directives remain adapter and policy extension points and are not claimed as automatic behavior. - -## Measured token breakdown - -```python -from marginal import extract_common_token_usage - -usage = extract_common_token_usage(response) -print(usage.input_tokens) -print(usage.cached_input_tokens) -print(usage.output_tokens) -print(usage.reasoning_tokens) -print(usage.total_tokens) -``` - -The normalized fields are additive: `input_tokens` means uncached input, while cached input is reported separately. - -## Failed calls that still consumed resources - -Some provider calls fail after compute was consumed. Supply a failure usage extractor to keep accounting truthful while preserving the original exception: - -```python -result = budgeted_call( - treasury, - client.responses.create, - action=action, - failure_usage_extractor=lambda error, estimate: measured_or_best_known_cost(error), - **request, -) ``` -Returning `None` means no external spend was observed and releases the reservation. Returning `Cost` settles the failed action. - -## Policy replay - -```bash -marginal ledger-validate marginal-ledger.jsonl -marginal ledger-report marginal-ledger.jsonl -marginal replay marginal-ledger.jsonl --profile balanced -marginal ledger-export marginal-ledger.jsonl safe-export.jsonl \ - --privacy-profile safe_telemetry --privacy-key-file .marginal/export.key -marginal ledger-export marginal-ledger.jsonl aggregate.jsonl \ - --privacy-profile aggregate_export --minimum-group-size 5 -``` +The protocol defines consistent events, capabilities, usage fields, decisions, settlement, and outcome contracts. Vendor-specific adapters are developed as thin integrations; they do not duplicate the economic policy. -Replay re-evaluates recorded proposed actions under another policy. It is an off-policy diagnostic based on recorded actions and costs. It is **not causal proof**, does not simulate missing trajectories, and does not establish preserved task quality. +### Integration status -## Execution modes - -| Mode | Applied behavior | Intended use | +| Environment | Current status | Intended capability | |---|---|---| -| `shadow` | Execute every proposed action; record recommendation | Safe data collection and calibration | -| `recommend` | Execute every proposed action; surface recommendation | Human/agent advisory integrations | -| `enforce` | Apply allow/deny and hard-budget decisions | Validated production control | - -`fund_best` remains an active selection API in every mode because MARGINAL is explicitly being asked to choose among candidates. - -## Reference policy profiles - -```python -from marginal import build_policy - -quality_first = build_policy("quality-first") -balanced = build_policy("balanced") -token_saver = build_policy("token-saver") -strict_budget = build_policy("strict-budget") -``` - -These are transparent reference defaults, not universally calibrated guarantees. Production policies should be validated against representative tasks and verifiers. - -## Decision model - -The reference policy converts configured dimensions into a common USD-denominated value: - -```text -expected value = capped expected success gain × outcome value -cost value = direct USD + token shadow cost + latency shadow cost + risk shadow cost -marginal score = expected value − cost value -ROI = expected value ÷ cost value -``` - -A recommended action must remain affordable, preserve verification reserves, avoid an exact duplicate under the chosen fingerprint scope, remain below the success target, and clear expected-gain and ROI thresholds. - -## Reliable accounting - -```text -propose → evaluate → reserve → execute → settle actual cost - ↘ abort when no spend occurred - ↘ settle failure when spend occurred -``` - -If actual usage exceeds the reservation, MARGINAL records the real spend first. Enforce mode then raises `BudgetOverrun`. Shadow and recommend modes record the observed overrun without changing caller behavior. - -If a failure usage extractor itself fails, MARGINAL conservatively settles the reserved estimate, releases the reservation, and keeps the original execution exception primary. A measured failed action is not marked as a completed duplicate, so a legitimate retry remains possible. +| Core Python runtime | Available | Full allocation, accounting, ledger, replay | +| Universal Agent Protocol | Available | Adapter contract and capability negotiation | +| Codex | Roadmap | Reference integration and measured benchmark | +| OpenCode | Roadmap | Open-source adapter and research environment | +| Claude Code | Roadmap | Hook-based integration | +| GitHub Copilot CLI / coding agent | Roadmap | Integration where official control surfaces permit | -## Duplicate protection and state-aware retries +See the [full roadmap](ROADMAP.md). Planned adapters are not presented as completed integrations. -Guarded call fingerprints include the action, callable identity, arguments, and keyword arguments. Universal-agent actions additionally support: +## Privacy by design -- `exact`; -- `once_per_state`; -- `once_per_phase`; -- `allow_retry`. +Not recording prompts is not enough: identifiers, action names, model names, metadata, verifier details, and exception text can still expose sensitive information. -This lets an adapter distinguish an accidental repeated read from a legitimate test rerun after the workspace changes. Shadow Mode can observe concurrent semantic duplicates without blocking them while still reserving and settling each execution separately. +MARGINAL therefore separates operational evidence from shareable telemetry: -## Hierarchical agent budgets - -```python -root = Treasury(BudgetLimits(max_tokens=200_000, max_usd=5.0), mode="shadow") -research = root.child("research", BudgetLimits(max_tokens=40_000, max_usd=1.0)) -verification = root.child( - "verification", - BudgetLimits(max_tokens=30_000, max_usd=0.75), -) -``` - -A child authorization reserves capacity from every ancestor under one shared lock. Settlement charges every level, preventing parallel sub-agents from oversubscribing a parent budget. - -## Trace and inspect decisions - -`JsonlTraceSink` preserves the v0.1 trace format. `JsonlDecisionLedger` is the strict v0.2 evidence format with schema, identity, sequencing, and correlation fields. - -```bash -marginal validate marginal-trace.jsonl -marginal report marginal-trace.jsonl -marginal ledger-validate marginal-ledger.jsonl -marginal ledger-report marginal-ledger.jsonl -marginal ledger-export marginal-ledger.jsonl aggregate.jsonl \ - --privacy-profile aggregate_export --minimum-group-size 5 -``` +| Profile | Purpose | +|---|---| +| `LOCAL_FULL` | Full operational ledger on a trusted local filesystem | +| `SAFE_TELEMETRY` | Removes free text and pseudonymizes identifiers with a local key | +| `AGGREGATE_EXPORT` | Produces generalized grouped rows with no identifiers or timestamps | -`LOCAL_FULL` is the backward-compatible ledger default. Use `SAFE_TELEMETRY` for strict -local telemetry and `AGGREGATE_EXPORT` for grouped sharing. Aggregate groups smaller than five -records are suppressed by default, and export destinations are never overwritten automatically. +Aggregate exports suppress groups smaller than five records by default to reduce re-identification risk. Pseudonymization is not anonymization; exports must still be reviewed before sharing. -A `CompositeTraceSink` can fan events to multiple sinks in order, but writes across different sinks are not an atomic distributed transaction. Use one authoritative ledger when atomic evidence is required. +Read the [privacy model](docs/privacy.md) and [security policy](SECURITY.md). -## Killer Demo +## Evidence, not hype -The bundled deterministic demo still demonstrates the allocation mechanism: +MARGINAL includes a deterministic Killer Demo that fixes the same code defect with a baseline workflow and a MARGINAL-funded workflow. ```bash -marginal killer-demo --output killer-demo-output +marginal killer-demo --output-dir demo-output ``` -It uses declared action-cost estimates and a deterministic verifier. It is not provider telemetry, a production benchmark, or a universal savings claim. - -[Open the committed demo report →](demos/killer-demo/RESULTS.md) +The demo uses declared action-cost estimates. It is useful for understanding allocation behavior, but it is **not provider telemetry and not a production savings claim**. -## Synthetic benchmark - -The bundled deterministic benchmark exercises policy, reservation, accounting, and reproducibility: +Public evaluation compares matched runs with the same agent, model, prompt, tools, limits, task order, and verifier: ```bash -marginal demo +marginal public-eval baseline.jsonl marginal.jsonl ``` -Its declared token, USD, and latency values are synthetic. The result tests mechanics and must not be presented as provider-measured savings. - -## Public benchmarking - -Real evaluations should compare the same model, task, tools, limits, and verifier with and without MARGINAL. The comparator accepts an explicit confidence level and preregistered quality margin: - -```bash -marginal public-eval baseline.jsonl marginal.jsonl \ - --confidence-level 0.95 --quality-margin-pp 1.0 -``` +The report covers: -Report: - -- resolved rate and confidence intervals; -- input, cached input, output, reasoning, and total tokens where available; -- direct cost, latency, tool calls, and sub-agent calls; -- cost per verified successful task; +- resolve-rate delta and quality non-inferiority; +- total and per-resolved-task token cost; +- USD, latency, and tool calls; - regressions and recoveries; -- policy and estimator identities; -- raw paired evidence without dropped failures. - -Savings without preserved quality are not optimization. - -See [`docs/public-benchmarks.md`](docs/public-benchmarks.md) and [`docs/benchmarking.md`](docs/benchmarking.md). +- bootstrap uncertainty. -## How MARGINAL differs - -| Category | Primary question | MARGINAL relationship | -|---|---|---| -| Hard budget / circuit breaker | Can this session spend more? | Complementary; MARGINAL also evaluates expected value | -| Model router | Which model should answer? | A model choice can be represented as a candidate action | -| Prompt compressor | Can this call use fewer tokens? | Complementary; MARGINAL may avoid the entire action | -| Workflow optimizer | Can a fixed flow be simplified? | MARGINAL makes state-aware online decisions | -| Observability | What was spent? | MARGINAL decides before spending and settles afterward | -| Decision Ledger | Why did policy behavior change? | Records versioned recommendation, application, cost, and outcome evidence | +A token reduction without preserved verified outcomes is not considered a successful result. -## Core primitives - -| Primitive | Responsibility | -|---|---| -| `Action`, `Cost`, `TokenUsage` | Describe proposed work and estimated or measured resources | -| `Decision`, `Allocation` | Expose applied behavior, recommendation, reason, score, and funded candidate | -| `BudgetLimits`, `BudgetLedger` | Enforce hard limits, reservations, and verification reserves | -| `MarginalPolicy`, `ValueEstimator` | Score expected marginal value with versioned identities | -| `Treasury` | Coordinate ranking, authorization, settlement, hierarchy, evidence, and outcomes | -| `JsonlDecisionLedger` | Persist strict, append-only learning-loop evidence with an explicit privacy profile | -| `PrivacyProfile`, `export_decision_ledger` | Pseudonymize safe telemetry or create grouped aggregate exports | -| `AgentAction`, `AgentDecision`, `AgentEvent` | Normalize engine-adapter communication | -| `UniversalRuntime` | Correlate one engine session with transactional core operations | -| `replay_ledger` | Compare policy recommendations over recorded actions without causal claims | +See [Public benchmark protocol](docs/public-benchmarks.md) and [Killer Demo results](demos/killer-demo/RESULTS.md). ## Architecture ```text -AI development agent - │ native hook/event - ▼ -thin engine adapter - │ universal protocol - ▼ -UniversalRuntime → Treasury → policy → versioned estimator - │ │ - │ ├─ reserve / settle / abort / failure settlement - │ └─ Decision Ledger → privacy profile → outcome / replay / export - ▼ -allow / deny today; richer negotiated directives through protocol extensions +AI development agents +Codex · Claude Code · Copilot · OpenCode · others + │ + thin engine adapters + │ + Universal Agent Protocol + │ + ┌────────────────┼────────────────┐ + │ │ │ + Value Estimator Treasury Decision Ledger + │ │ │ + └────────── Decision Policy ──────┘ + │ + observe · recommend · enforce ``` -See [`docs/architecture.md`](docs/architecture.md). +MARGINAL is deliberately modular: -## Project status +- the **core** evaluates and accounts; +- the **runtime** coordinates sessions and adapters; +- the **ledger** preserves evidence; +- privacy exports transform data for controlled sharing; +- external frameworks retain ownership of execution. -MARGINAL `v0.2.0` is the **Learning Loop Foundation**. It provides a universal protocol, local runtime, non-blocking shadow evaluation, schema-versioned evidence, explicit privacy profiles, outcome recording, contextual historical estimates, failure settlement, and off-policy replay. +Read the [architecture](docs/architecture.md) and [API reference](docs/api.md). -It does not yet claim complete vendor-specific adapters, causal marginal-value estimation, automatic regret minimization, or guaranteed savings on arbitrary workloads. The next validation milestone is a real paired Codex integration using measured telemetry and a predefined quality non-inferiority criterion. +## Project status -## Roadmap +`v0.2.0` provides the Learning Loop Foundation, privacy profiles, Universal Agent Protocol, versioned evidence, policy replay, and a dependency-free core. -The project remains one product and one repository. Future Codex, OpenCode, Claude Code, GitHub Copilot, and other integrations will be thin adapters over the same protocol and core. +The active milestone is **v0.3 — Codex Reference Integration**: measured token telemetry, matched baseline runs, a 10-task canary, and a preregistered public evaluation before broader enforcement claims. -[View the full product roadmap →](ROADMAP.md) +[View the roadmap →](ROADMAP.md) ## Documentation -- [Quickstart](docs/quickstart.md) -- [Concepts](docs/concepts.md) -- [Architecture](docs/architecture.md) -- [API reference](docs/api.md) -- [Learning loop](docs/learning-loop.md) -- [Universal runtime](docs/universal-runtime.md) -- [Privacy profiles](docs/privacy.md) -- [Integrations](docs/integrations.md) -- [Benchmarking](docs/benchmarking.md) -- [Public benchmark protocol](docs/public-benchmarks.md) -- [Research and prior art](docs/research.md) -- [FAQ](docs/faq.md) -- [Governance](docs/governance.md) -- [Contributing](CONTRIBUTING.md) -- [Security](SECURITY.md) - -## Research lineage - -MARGINAL is an independent open-source reference implementation inspired by the research direction described in Siqi Zhu’s position paper, “Agentic AI Systems Should Be Designed as Marginal Token Allocators.” The paper proposes an economic framing; this repository focuses on a usable runtime contract, accounting, evidence, tests, integrations, and honest validation. +| Start here | Deep dives | +|---|---| +| [Quickstart](docs/quickstart.md) | [Architecture](docs/architecture.md) | +| [Core concepts](docs/concepts.md) | [API reference](docs/api.md) | +| [Integration guide](docs/integrations.md) | [Privacy profiles](docs/privacy.md) | +| [Benchmarking](docs/benchmarking.md) | [Public benchmark protocol](docs/public-benchmarks.md) | +| [Roadmap](ROADMAP.md) | [Security](SECURITY.md) | +| [Changelog](CHANGELOG.md) | [Governance](docs/governance.md) | + +The [project website](https://signallayerlabs.github.io/Marginal/) provides the product-level overview; GitHub remains the source of truth for code, evidence, releases, and technical documentation. ## Contributing -Contributions are welcome for adapters, estimator implementations, benchmark scenarios, schemas, documentation, and independent validation. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a pull request. +Contributions are welcome across the core, protocol, adapters, privacy, benchmarks, and documentation. + +Before opening a pull request: + +```bash +ruff format --check . +ruff check . +mypy src/marginal +pytest -q +python -m build +python -m twine check dist/* +``` + +Read [`CONTRIBUTING.md`](CONTRIBUTING.md) and the [governance model](docs/governance.md). ## Citation -Research and technical work can cite the repository using [`CITATION.cff`](CITATION.cff). +```bibtex +@software{marginal2026, + title = {MARGINAL: Compute Governance for AI Agents}, + author = {SignalLayer Labs and contributors}, + year = {2026}, + url = {https://github.com/SignalLayerLabs/Marginal}, + license = {Apache-2.0} +} +``` ## License diff --git a/VISUAL_STUDIO_COMMIT_PROMPT.md b/VISUAL_STUDIO_COMMIT_PROMPT.md new file mode 100644 index 0000000..07eca37 --- /dev/null +++ b/VISUAL_STUDIO_COMMIT_PROMPT.md @@ -0,0 +1,47 @@ +# Visual Studio / GitHub Copilot Commit Prompt + +Apply this ZIP to the root of the checked-out `SignalLayerLabs/Marginal` repository, preserving all paths. + +## Procedure + +1. Create branch `docs/readme-pages-redesign`. +2. Copy every ZIP file into the repository. +3. Search `.github/workflows/` for `actions/deploy-pages`. Exactly one active Pages deployer must remain. Keep `.github/workflows/pages.yml`; remove or consolidate any older Pages/Killer Demo deployer. +4. Confirm these existing files are present: + `assets/marginal-readme-hero.png`, `demos/killer-demo/RESULTS.md`, `docs/quickstart.md`, `docs/architecture.md`, `docs/privacy.md`, `docs/api.md`, `docs/integrations.md`, `docs/benchmarking.md`, `docs/public-benchmarks.md`, `ROADMAP.md`, `SECURITY.md`, `CONTRIBUTING.md`, `LICENSE`. +5. Preserve the claim guardrails: + - vendor adapters remain labeled roadmap/planned; + - the Killer Demo remains deterministic and estimate-based; + - no guaranteed per-request savings; + - measured savings require preserved verified quality; + - pseudonymization is not anonymization. +6. Run: + ```bash + python scripts/validate_readme_pages.py + ruff format --check . + ruff check . + mypy src/marginal + pytest -q + python -m build + python -m twine check dist/* + ``` +7. Preview: + ```bash + python -m http.server 8000 --directory site + ``` + Check desktop/mobile, keyboard navigation, links, and contrast. +8. In GitHub Settings → Pages, choose **GitHub Actions**. +9. Update repository About: + - Description: `Open-source compute governance and token optimization for AI agents. Observe, measure, learn and enforce which model calls, tools, retries and sub-agents are worth the cost.` + - Website: `https://signallayerlabs.github.io/Marginal/` + - Topics: `ai-agents`, `llm`, `token-optimization`, `cost-optimization`, `compute-governance`, `agent-observability`, `codex`, `claude-code`, `github-copilot`, `opencode`, `python`, `local-first` +10. Commit: `docs: redesign README and launch product website` +11. Push and open PR: `docs: redesign README and launch GitHub Pages website`. + +PR summary: +- concise SEO-oriented technical README; +- accessible dependency-free product website; +- one consolidated Pages deployment including Killer Demo; +- website operations and claim guardrails documented. + +Include exact verification outputs in the PR. Do not merge if a second workflow still deploys Pages. diff --git a/docs/superpowers/plans/2026-08-06-readme-pages.md b/docs/superpowers/plans/2026-08-06-readme-pages.md new file mode 100644 index 0000000..300ba09 --- /dev/null +++ b/docs/superpowers/plans/2026-08-06-readme-pages.md @@ -0,0 +1,17 @@ +# README and GitHub Pages Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Replace the long README with a concise technical landing page and add a dependency-free GitHub Pages website. + +**Architecture:** README, website, docs, and roadmap have distinct responsibilities. One Pages workflow assembles the static site, existing hero asset, and Killer Demo. + +**Tech Stack:** GitHub Markdown, semantic HTML5, CSS, vanilla JavaScript, GitHub Actions Pages. + +## Tasks + +1. Replace `README.md`, preserving install, quickstart, evidence, privacy, roadmap, docs, contribution, citation, and license. +2. Add `site/index.html`, styles, navigation script, robots, sitemap, and 404 page. +3. Add one `.github/workflows/pages.yml` deployment that also publishes the Killer Demo. +4. Add `docs/website.md` and update `CHANGELOG.md`. +5. Run `scripts/validate_readme_pages.py`, repository CI checks, local preview, and final diff review. diff --git a/docs/superpowers/specs/2026-08-06-readme-pages-design.md b/docs/superpowers/specs/2026-08-06-readme-pages-design.md new file mode 100644 index 0000000..e833ca6 --- /dev/null +++ b/docs/superpowers/specs/2026-08-06-readme-pages-design.md @@ -0,0 +1,19 @@ +# README and GitHub Pages Redesign + +## Goal + +Turn the repository entrance into a fast technical landing page and provide a separate product website for discovery, positioning, and adoption. + +## Information architecture + +- README: concise developer-facing landing page. +- GitHub Pages: marketing-oriented product page. +- Existing docs: detailed technical source of truth. +- Roadmap: delivery status and future milestones. +- GitHub: code, evidence, releases, issues, and contribution workflow. + +## Guardrails + +Explain the product in the first screen, use search-relevant terminology naturally, keep claims tied to evidence, separate deterministic demonstrations from measured benchmarks, and label unfinished engine adapters as planned. + +The website uses static HTML, CSS, and minimal JavaScript, with no third-party runtime dependencies, tracking, or analytics. diff --git a/docs/website.md b/docs/website.md new file mode 100644 index 0000000..f0dc582 --- /dev/null +++ b/docs/website.md @@ -0,0 +1,50 @@ +# MARGINAL website + +The product website is a dependency-free static site published through GitHub Pages at: + +`https://signallayerlabs.github.io/Marginal/` + +## Responsibility split + +- `README.md` is the fast technical entry point for developers. +- `site/` is the product-level marketing and discovery experience. +- `docs/` remains the source for detailed technical documentation. +- GitHub remains the source of truth for code, releases, benchmarks, issues, and evidence. +- `demos/killer-demo/` is published under `/demo/` by the Pages workflow. + +The website must not make claims stronger than the repository evidence. Planned engine adapters remain labeled as planned. The Killer Demo remains labeled as a deterministic demonstration based on declared cost estimates. + +## Deployment + +GitHub Pages must use **GitHub Actions** as its source. Only one workflow in the repository may call `actions/deploy-pages`. Before merging, search `.github/workflows/` and remove or consolidate any previous Pages workflow. + +The workflow assembles: + +```text +site/ → / +assets/marginal-readme-hero.png → /assets/ +demos/killer-demo/ → /demo/ +``` + +## Local preview + +```bash +python -m http.server 8000 --directory site +``` + +To reproduce the deployment layout: + +```bash +rm -rf _site +mkdir -p _site/assets _site/demo +cp -R site/. _site/ +cp assets/marginal-readme-hero.png _site/assets/marginal-readme-hero.png +cp -R demos/killer-demo/. _site/demo/ +python -m http.server 8000 --directory _site +``` + +## SEO, accessibility, and privacy guardrails + +The site includes one descriptive `h1`, canonical and social metadata, `robots.txt`, sitemap, semantic structure, keyboard navigation, responsive layouts, and reduced-motion support. + +It contains no analytics or third-party runtime scripts. Any future analytics integration requires a documented privacy review. diff --git a/scripts/validate_readme_pages.py b/scripts/validate_readme_pages.py new file mode 100644 index 0000000..88606f5 --- /dev/null +++ b/scripts/validate_readme_pages.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 +import re +from html.parser import HTMLParser +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +class Parser(HTMLParser): + def __init__(self): + super().__init__() + self.title = "" + self.in_title = False + self.h1 = 0 + self.meta = {} + self.scripts = [] + self.styles = [] + + def handle_starttag(self, tag, attrs): + data = {k: v or "" for k, v in attrs} + if tag == "title": + self.in_title = True + elif tag == "h1": + self.h1 += 1 + elif tag == "meta": + key = data.get("name") or data.get("property") + if key: + self.meta[key] = data.get("content", "") + elif tag == "script": + self.scripts.append(data.get("src", "")) + elif tag == "link" and data.get("rel") == "stylesheet": + self.styles.append(data.get("href", "")) + + def handle_endtag(self, tag): + if tag == "title": + self.in_title = False + + def handle_data(self, data): + if self.in_title: + self.title += data + + +readme = (ROOT / "README.md").read_text(encoding="utf-8") +words = len(re.findall(r"\b[\w\'-]+\b", readme)) +assert 1200 <= words <= 2200, f"README words: {words}" +for heading in [ + "# MARGINAL", + "## Why MARGINAL", + "## How it works", + "## Install", + "## Quickstart", + "## The Learning Loop Foundation", + "## Universal Agent Runtime", + "## Privacy by design", + "## Evidence, not hype", + "## Project status", + "## Documentation", +]: + assert heading in readme, heading +for forbidden in [ + "guarantees fewer tokens", + "saves tokens on every request", + "Codex adapter is available", + "Claude Code adapter is available", +]: + assert forbidden.lower() not in readme.lower(), forbidden + +required = [ + "docs/quickstart.md", + "docs/architecture.md", + "docs/privacy.md", + "docs/api.md", + "docs/integrations.md", + "docs/benchmarking.md", + "docs/public-benchmarks.md", + "ROADMAP.md", + "SECURITY.md", + "CONTRIBUTING.md", + "LICENSE", + "assets/marginal-readme-hero.png", + "demos/killer-demo/RESULTS.md", +] +missing = [p for p in required if not (ROOT / p).exists()] +assert not missing, missing + +parser = Parser() +parser.feed((ROOT / "site/index.html").read_text(encoding="utf-8")) +assert parser.title.strip() +assert parser.h1 == 1 +for key in ["description", "robots", "og:title", "og:description", "og:url", "twitter:card"]: + assert parser.meta.get(key), key +assert parser.styles == ["styles.css"] +assert parser.scripts == ["app.js"] +assert not any(x.startswith(("http://", "https://")) for x in parser.styles + parser.scripts) + +for path in [ + "site/styles.css", + "site/app.js", + "site/robots.txt", + "site/sitemap.xml", + "site/404.html", +]: + assert (ROOT / path).is_file(), path + +workflow = (ROOT / ".github/workflows/pages.yml").read_text(encoding="utf-8") +for token in [ + "actions/configure-pages@v5", + "actions/upload-pages-artifact@v3", + "actions/deploy-pages@v4", + "demos/killer-demo", + "assets/marginal-readme-hero.png", +]: + assert token in workflow, token + +deployers = [] +for pattern in ("*.yml", "*.yaml"): + for path in (ROOT / ".github/workflows").glob(pattern): + if "actions/deploy-pages" in path.read_text(encoding="utf-8"): + deployers.append(path.relative_to(ROOT).as_posix()) +assert deployers == [".github/workflows/pages.yml"], deployers + +print(f"README words: {words}") +print("README structure and claims: PASS") +print("Referenced files: PASS") +print("Website SEO and dependency audit: PASS") +print("Pages workflow consolidation: PASS") diff --git a/site/404.html b/site/404.html new file mode 100644 index 0000000..99ade7e --- /dev/null +++ b/site/404.html @@ -0,0 +1 @@ +Page not found — MARGINAL

404

Page not found.

The requested page does not exist.

Return to MARGINAL
diff --git a/site/app.js b/site/app.js new file mode 100644 index 0000000..baad58e --- /dev/null +++ b/site/app.js @@ -0,0 +1,2 @@ +const button=document.querySelector(".nav-toggle");const links=document.querySelector(".nav-links"); +if(button&&links){button.addEventListener("click",()=>{const open=links.classList.toggle("open");button.setAttribute("aria-expanded",String(open))});links.addEventListener("click",event=>{if(event.target instanceof HTMLAnchorElement){links.classList.remove("open");button.setAttribute("aria-expanded","false")}})} \ No newline at end of file diff --git a/site/index.html b/site/index.html new file mode 100644 index 0000000..2588ae2 --- /dev/null +++ b/site/index.html @@ -0,0 +1,146 @@ + + + + + + MARGINAL — Compute Governance and Token Optimization for AI Agents + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+
+
+

Open-source compute governance for AI agents

+

Fund only the next action worth taking.

+

MARGINAL helps AI agents decide whether the next model call, tool call, search, retry, review or sub-agent is worth its token cost.

+
+ Get started + View roadmap +
+
    +
  • Local first
  • Provider neutral
  • Zero mandatory dependencies
  • Apache-2.0
    • +
+
+
+
Agent proposes action
↓
+
Estimate value versus cost
↓
+
ALLOWDENYSHADOW
+
↓
Settle actual usage + outcome
+
+
+ +
+

The missing layer

+

Budgets say what an agent can afford. MARGINAL asks what deserves funding.

+

Agent runtimes often execute work because a model requested it or a hard limit has not been reached. MARGINAL compares expected improvement with tokens, cost, latency, risk, remaining budget and verification needs before compute is committed.

+
+ +
+

How it works

Transactional governance, not token counting

+
+
01

Observe

Capture proposed actions and context through one engine-neutral protocol.

+
02

Evaluate

Estimate marginal gain, uncertainty and full economic cost.

+
03

Reserve

Atomically protect budget and verification capacity before execution.

+
04

Settle

Record measured usage, failures, overruns and verified outcomes.

+
05

Learn

Replay versioned policies and improve calibration without overstating causality.

+
+
+ +
+

Why it is different

Built for accountable autonomy

+
+

Shadow before enforcement

Observe recommendations without changing agent behavior, then enforce only after representative validation.

+

Real accounting lifecycle

Reserve, execute, settle, abort and report overruns across hierarchical treasuries.

+

Protected verification

Keep capacity available for tests and evidence instead of optimizing an agent into premature confidence.

+

Versioned evidence

Decision Ledger records correlate policy, estimator, cost, outcome and runtime identity for audit and replay.

+

Universal protocol

Thin adapters connect coding agents while the economic policy remains in one core.

+

Measured claims

Token reduction counts only when verified outcomes remain within a predefined quality constraint.

+
+
+ +
+

The learning loop

From static policy to evidence-driven allocation

+

MARGINAL's defensible advantage is not a single ROI formula. It is the closed loop between observed decisions, measured outcomes, versioned estimators, policy replay and calibration.

+

Task success is kept separate from action-level causal attribution. Recorded correlation is not presented as causal proof.

+
+
  1. Observe decisions
  2. Measure actual cost and outcomes
  3. Estimate marginal value with uncertainty
  4. Allocate budget
  5. Measure calibration and regret
  6. Improve the policy
+
+ +
+

Privacy by design

Operational evidence stays local. Shareable data is transformed deliberately.

+

Prompt-free telemetry can still leak through identifiers, names and metadata. MARGINAL classifies fields and provides explicit export profiles.

+
+
+
LOCAL_FULLComplete operational ledger for trusted local storage.
+
SAFE_TELEMETRYFree text removed and identifiers pseudonymized with a local key.
+
AGGREGATE_EXPORTGeneralized groups without identifiers; small groups suppressed by default.
+
+
+ +
+

One product, multiple engines

Universal foundation first. Thin adapters next.

+
+
Available

Core runtime

Policy, treasury, ledger, privacy, replay and universal protocol.

+
Next

Codex

Reference adapter and matched measured benchmark.

+
Planned

OpenCode

Open-source adapter and experimentation environment.

+
Planned

Claude Code

Hook-based integration using shared protocol contracts.

+
Planned

GitHub Copilot

Integration where official control surfaces permit enforcement.

+
+
Read the full roadmap
+
+ +
+

Evidence, not hype

Optimization is successful only when quality is preserved.

+

The bundled Killer Demo is deterministic and uses declared action costs. It explains the mechanism; it is not provider telemetry or a universal savings claim.

+

Public evaluation requires matched model, prompt, tools, limits and verifier, then reports tokens per verified successful task, quality delta and uncertainty.

+ Read the benchmark protocol → +
+
+ +
+

Build economically disciplined agents

+

Observe first. Measure honestly. Enforce what the evidence supports.

+
+ Install MARGINAL + Join the project +
+
+
+ + + + diff --git a/site/robots.txt b/site/robots.txt new file mode 100644 index 0000000..d4f285d --- /dev/null +++ b/site/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://signallayerlabs.github.io/Marginal/sitemap.xml diff --git a/site/sitemap.xml b/site/sitemap.xml new file mode 100644 index 0000000..e9beff8 --- /dev/null +++ b/site/sitemap.xml @@ -0,0 +1,2 @@ + +https://signallayerlabs.github.io/Marginal/weekly1.0https://signallayerlabs.github.io/Marginal/demo/monthly0.7 diff --git a/site/styles.css b/site/styles.css new file mode 100644 index 0000000..692786a --- /dev/null +++ b/site/styles.css @@ -0,0 +1,19 @@ +:root{--bg:#080b10;--surface:#10151d;--surface2:#151c26;--text:#f4f7fb;--muted:#aab5c4;--line:#273140;--accent:#91ff63;--max:1180px} +*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--bg);color:var(--text);font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;line-height:1.65}a{color:inherit} +.skip-link{position:absolute;left:-9999px}.skip-link:focus{left:1rem;top:1rem;z-index:100;background:var(--text);color:var(--bg);padding:.75rem 1rem} +.shell{width:min(calc(100% - 2rem),var(--max));margin-inline:auto}.narrow{max-width:790px}.center{text-align:center;justify-content:center} +.site-header{position:sticky;top:0;z-index:20;background:rgba(8,11,16,.9);border-bottom:1px solid var(--line);backdrop-filter:blur(16px)} +.nav{min-height:72px;display:flex;align-items:center;justify-content:space-between;gap:2rem}.brand{display:inline-flex;align-items:center;gap:.7rem;text-decoration:none;font-weight:800;letter-spacing:.08em}.brand-mark{display:grid;place-items:center;width:34px;height:34px;color:var(--bg);background:var(--accent);border-radius:8px} +.nav-links{display:flex;align-items:center;gap:1.35rem}.nav-links a{text-decoration:none;color:var(--muted);font-size:.94rem}.nav-links a:hover,.nav-links a:focus{color:var(--text)}.nav-toggle{display:none} +.button{display:inline-flex;align-items:center;justify-content:center;min-height:48px;padding:.7rem 1.15rem;border-radius:10px;background:var(--accent);color:#071006;text-decoration:none;font-weight:750;border:1px solid var(--accent)}.button:hover,.button:focus{filter:brightness(1.08);transform:translateY(-1px)}.button-secondary{background:transparent;color:var(--text);border-color:var(--line)}.button-small{min-height:38px;padding:.45rem .8rem;color:#071006!important} +.hero{min-height:720px;display:grid;grid-template-columns:1.25fr .75fr;align-items:center;gap:4rem;padding-block:7rem 5rem}.eyebrow{color:var(--accent);text-transform:uppercase;letter-spacing:.14em;font-size:.78rem;font-weight:800} +h1{font-size:clamp(3rem,7vw,6.4rem);line-height:.96;letter-spacing:-.055em;margin:.5rem 0 1.4rem;max-width:900px}h2{font-size:clamp(2rem,4.2vw,4rem);line-height:1.05;letter-spacing:-.04em;margin:.45rem 0 1.2rem}h3{line-height:1.2}.hero-lead{color:var(--muted);font-size:clamp(1.1rem,2vw,1.35rem);max-width:720px}.hero-actions{display:flex;gap:.8rem;margin-top:2rem;flex-wrap:wrap}.trust-row{display:flex;flex-wrap:wrap;gap:.7rem 1.25rem;list-style:none;padding:0;margin:2.2rem 0 0;color:var(--muted);font-size:.9rem}.trust-row li:before{content:"✓";color:var(--accent);margin-right:.4rem} +.hero-panel{border:1px solid var(--line);background:linear-gradient(160deg,var(--surface2),var(--surface));padding:2rem;border-radius:20px;box-shadow:0 30px 80px rgba(0,0,0,.35)}.flow-node{padding:1rem;border:1px solid var(--line);border-radius:10px;text-align:center;background:rgba(255,255,255,.02)}.flow-node.accent{border-color:var(--accent)}.flow-arrow{text-align:center;color:var(--accent);padding:.4rem}.decision-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:.5rem}.decision-grid span{border:1px solid var(--line);border-radius:8px;padding:.7rem .3rem;text-align:center;font-size:.75rem;font-weight:800} +.section{padding-block:6.5rem;border-top:1px solid var(--line)}.problem,.feature-section,.privacy-section,.evidence-section{background:var(--surface)}.problem{text-align:center}.problem p:last-child{color:var(--muted)}.section-heading{max-width:760px;margin-bottom:3rem} +.steps{display:grid;grid-template-columns:repeat(5,1fr);gap:1rem}.steps article,.feature-grid article,.roadmap-grid article{border:1px solid var(--line);border-radius:14px;padding:1.35rem;background:var(--surface)}.steps span,.roadmap-grid span{color:var(--accent);font-size:.8rem;font-weight:800;text-transform:uppercase;letter-spacing:.1em}.steps p,.feature-grid p,.roadmap-grid p{color:var(--muted);font-size:.94rem} +.feature-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:1rem}.split{display:grid;grid-template-columns:1fr 1fr;gap:5rem;align-items:start}.loop-list{list-style:none;padding:0;margin:0;counter-reset:loop}.loop-list li{counter-increment:loop;padding:1rem 0;border-bottom:1px solid var(--line);font-weight:700}.loop-list li:before{content:"0" counter(loop);color:var(--accent);margin-right:1rem;font-size:.8rem}.fine-print{color:var(--muted);font-size:.9rem} +.privacy-cards{display:grid;gap:.8rem}.privacy-cards article{display:grid;gap:.2rem;padding:1.2rem;border:1px solid var(--line);border-radius:12px}.privacy-cards strong{color:var(--accent)}.privacy-cards span{color:var(--muted)}.roadmap-grid{display:grid;grid-template-columns:repeat(5,1fr);gap:1rem;margin-bottom:2.5rem}.roadmap-grid .complete{border-color:var(--accent)}.text-link{color:var(--accent);font-weight:750;text-decoration:none}.cta{background:radial-gradient(circle at 50% 20%,rgba(145,255,99,.13),transparent 45%)} +footer{padding-block:3rem;border-top:1px solid var(--line);color:var(--muted)}.footer-grid{display:grid;grid-template-columns:2fr 1fr 1fr;gap:2rem}.footer-grid div{display:flex;flex-direction:column;gap:.4rem;align-items:flex-start}.footer-grid p{margin:0}.footer-grid a{text-decoration:none} +@media(max-width:900px){.hero,.split{grid-template-columns:1fr}.hero{min-height:auto;gap:2.5rem;padding-top:5rem}.steps{grid-template-columns:repeat(2,1fr)}.feature-grid{grid-template-columns:repeat(2,1fr)}.roadmap-grid{grid-template-columns:repeat(2,1fr)}.nav-toggle{display:inline-flex;background:transparent;border:1px solid var(--line);color:var(--text);padding:.55rem .75rem;border-radius:8px}.nav-links{display:none;position:absolute;left:1rem;right:1rem;top:72px;background:var(--surface);border:1px solid var(--line);border-radius:12px;padding:1rem;flex-direction:column;align-items:stretch}.nav-links.open{display:flex}} +@media(max-width:600px){h1{font-size:3.2rem}.section{padding-block:4.5rem}.steps,.feature-grid,.roadmap-grid,.footer-grid{grid-template-columns:1fr}.decision-grid{grid-template-columns:1fr}} +@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}*,*:before,*:after{transition:none!important;animation:none!important}}