loadout-ai 0.2.3 → 0.4.0

package/docs/assets/loadout-hero.svg

@@ -0,0 +1,259 @@
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="0 0 960 300"
+  role="img"
+  aria-labelledby="loadout-hero-title loadout-hero-description"
+>
+  <title id="loadout-hero-title">Choose an intentional agent loadout</title>
+  <desc id="loadout-hero-description">
+    A developer moves an extension from scattered configuration tiles into
+    organized managed equipment slots.
+  </desc>
+  <style>
+    svg {
+      color: #1f2328;
+    }
+    .quiet {
+      opacity: 0.48;
+    }
+    .soft {
+      opacity: 0.09;
+    }
+    .mid {
+      opacity: 0.72;
+    }
+    .line {
+      fill: none;
+      stroke: currentColor;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+    }
+    @media (prefers-color-scheme: dark) {
+      svg {
+        color: #f0f6fc;
+      }
+      .soft {
+        opacity: 0.13;
+      }
+    }
+  </style>
+
+  <!-- Loose, unmanaged configuration -->
+  <g class="line quiet" stroke-width="2">
+    <path d="M38 80C96 63 126 124 188 104S258 78 286 119" />
+    <path d="M47 221C96 183 128 235 179 202S247 174 286 204" />
+    <path d="M78 47C91 96 62 141 105 176S175 199 213 239" />
+    <path d="M205 53C177 91 219 133 187 158S122 167 88 211" />
+  </g>
+  <g class="line" stroke-width="2.5">
+    <g transform="rotate(-8 91 100)">
+      <rect
+        class="soft"
+        x="43"
+        y="72"
+        width="96"
+        height="56"
+        rx="10"
+        fill="currentColor"
+      />
+      <rect x="43" y="72" width="96" height="56" rx="10" />
+      <path d="M61 99l9-8m-9 8l9 8m18-16h29" />
+    </g>
+    <g transform="rotate(7 197 83)">
+      <rect
+        class="soft"
+        x="153"
+        y="57"
+        width="88"
+        height="52"
+        rx="10"
+        fill="currentColor"
+      />
+      <rect x="153" y="57" width="88" height="52" rx="10" />
+      <path d="M174 74v18m0-9h15m14-9v18m-7-9h14" />
+    </g>
+    <g transform="rotate(-5 113 190)">
+      <rect
+        class="soft"
+        x="64"
+        y="161"
+        width="98"
+        height="58"
+        rx="10"
+        fill="currentColor"
+      />
+      <rect x="64" y="161" width="98" height="58" rx="10" />
+      <path d="M86 179l-8 11 8 11m53-22l8 11-8 11m-34 4l15-30" />
+    </g>
+    <g transform="rotate(9 213 193)">
+      <rect
+        class="soft"
+        x="170"
+        y="166"
+        width="86"
+        height="54"
+        rx="10"
+        fill="currentColor"
+      />
+      <rect x="170" y="166" width="86" height="54" rx="10" />
+      <circle cx="190" cy="193" r="5" />
+      <circle cx="233" cy="181" r="5" />
+      <circle cx="233" cy="205" r="5" />
+      <path d="M195 191l33-9m-33 13l33 9" />
+    </g>
+  </g>
+  <g class="line" stroke-width="2.5">
+    <path d="M48 232v24h12" />
+    <path d="M64 232h12v24H64zM80 232h12v24H80z" />
+    <path d="M108 232H96v12h12v12H96" />
+    <path d="M124 232h-12v24h12m-12-12h10" />
+  </g>
+
+  <!-- Developer selecting one extension tile -->
+  <g class="line" stroke-width="3">
+    <circle class="soft" cx="333" cy="91" r="28" fill="currentColor" />
+    <circle cx="333" cy="91" r="28" />
+    <path d="M310 87c10-14 34-18 46-2M319 99c8 7 18 7 27 0" />
+    <path d="M331 119v61m-1-41l-40 3-28-17" />
+    <path d="M331 138l33-9 29 15" />
+    <path d="M315 180l-16 38m48-38l17 38" />
+    <path d="M282 125l-13 3 7 10" />
+    <rect
+      class="soft"
+      x="253"
+      y="111"
+      width="43"
+      height="31"
+      rx="7"
+      fill="currentColor"
+    />
+    <rect x="253" y="111" width="43" height="31" rx="7" />
+    <path d="M265 127h19m-9-8v16" />
+  </g>
+  <g class="line mid" stroke-width="3">
+    <path d="M283 226h119l18-47h-97" />
+    <path d="M298 227v22m89-22v22" />
+    <path d="M351 165h48" />
+  </g>
+
+  <!-- Management boundary and placement cue -->
+  <path
+    class="line quiet"
+    d="M456 39v222"
+    stroke-width="2"
+    stroke-dasharray="7 10"
+  />
+  <g class="line" stroke-width="3">
+    <path d="M403 125c30-18 48-23 72-13 14 6 22 18 31 28" />
+    <path d="M493 137l15 5-3-15" />
+  </g>
+  <g class="line" stroke-width="2.5">
+    <path d="M478 48V26l6 12 6-12v22" />
+    <path d="M494 48l6-22 6 22m-9-8h6" />
+    <path d="M510 48V26l12 22V26" />
+    <path d="M526 48l6-22 6 22m-9-8h6" />
+    <path d="M554 33v-7h-12v22h12V38h-6" />
+    <path d="M570 26h-12v22h12m-12-11h10" />
+    <path d="M574 26v22h5c9 0 9-22 0-22z" />
+  </g>
+
+  <!-- Calm, organized loadout rail -->
+  <rect
+    class="soft"
+    x="486"
+    y="75"
+    width="438"
+    height="154"
+    rx="25"
+    fill="currentColor"
+  />
+  <rect
+    class="line mid"
+    x="486"
+    y="75"
+    width="438"
+    height="154"
+    rx="25"
+    stroke-width="2.5"
+  />
+  <path class="line quiet" d="M508 244h394" stroke-width="2.5" />
+  <g class="line" stroke-width="3">
+    <g>
+      <rect
+        class="soft"
+        x="510"
+        y="103"
+        width="68"
+        height="96"
+        rx="13"
+        fill="currentColor"
+      />
+      <rect x="510" y="103" width="68" height="96" rx="13" />
+      <path d="M530 141l10 10-10 10m18 0h12" />
+    </g>
+    <g>
+      <rect
+        class="soft"
+        x="591"
+        y="103"
+        width="68"
+        height="96"
+        rx="13"
+        fill="currentColor"
+      />
+      <rect x="591" y="103" width="68" height="96" rx="13" />
+      <path
+        d="M620 132v12m11-12v12m-17 0h23v9c0 8-5 14-12 14s-12-6-12-14v-9m12 23v7"
+      />
+    </g>
+    <g>
+      <rect
+        class="soft"
+        x="672"
+        y="103"
+        width="68"
+        height="96"
+        rx="13"
+        fill="currentColor"
+      />
+      <rect x="672" y="103" width="68" height="96" rx="13" />
+      <circle cx="693" cy="151" r="6" />
+      <circle cx="720" cy="133" r="6" />
+      <circle cx="720" cy="169" r="6" />
+      <path d="M698 147l17-11m-17 19l17 11" />
+    </g>
+    <g>
+      <rect
+        class="soft"
+        x="753"
+        y="103"
+        width="68"
+        height="96"
+        rx="13"
+        fill="currentColor"
+      />
+      <rect x="753" y="103" width="68" height="96" rx="13" />
+      <path
+        d="M785 128c-8 0-9 5-9 12v4c0 5-3 7-8 7 5 0 8 2 8 7v4c0 7 1 12 9 12m4-46c8 0 9 5 9 12v4c0 5 3 7 8 7-5 0-8 2-8 7v4c0 7-1 12-9 12"
+      />
+    </g>
+    <g class="quiet">
+      <rect
+        x="834"
+        y="103"
+        width="68"
+        height="96"
+        rx="13"
+        stroke-dasharray="7 7"
+      />
+      <path d="M855 151h26" />
+    </g>
+  </g>
+  <g fill="currentColor">
+    <circle cx="544" cy="245" r="4" />
+    <circle cx="625" cy="245" r="4" />
+    <circle cx="706" cy="245" r="4" />
+    <circle cx="787" cy="245" r="4" />
+    <circle class="quiet" cx="868" cy="245" r="4" />
+  </g>
+</svg>

package/docs/assets/loadout-mark.svg

@@ -0,0 +1,54 @@
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  viewBox="0 0 600 168"
+  role="img"
+  aria-labelledby="loadout-mark-title loadout-mark-description"
+>
+  <title id="loadout-mark-title">Loadout</title>
+  <desc id="loadout-mark-description">
+    Five outlined loadout slots with a terminal prompt in the selected center
+    slot.
+  </desc>
+  <style>
+    :root {
+      color: #24292f;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        color: #f0f6fc;
+      }
+    }
+  </style>
+
+  <g
+    fill="none"
+    stroke="currentColor"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path
+      d="M69 44h64a12 12 0 0 1 12 12v64a12 12 0 0 1-12 12H69a12 12 0 0 1-12-12V56a12 12 0 0 1 12-12Z"
+      stroke-width="6"
+    />
+    <path
+      d="M170 44h64a12 12 0 0 1 12 12v64a12 12 0 0 1-12 12h-64a12 12 0 0 1-12-12V56a12 12 0 0 1 12-12Z"
+      stroke-width="6"
+    />
+    <path
+      d="M271 32h58a18 18 0 0 1 18 18v76a18 18 0 0 1-18 18h-58a18 18 0 0 1-18-18V50a18 18 0 0 1 18-18Z"
+      stroke-width="8"
+    />
+    <path
+      d="M366 44h64a12 12 0 0 1 12 12v64a12 12 0 0 1-12 12h-64a12 12 0 0 1-12-12V56a12 12 0 0 1 12-12Z"
+      stroke-width="6"
+    />
+    <path
+      d="M467 44h64a12 12 0 0 1 12 12v64a12 12 0 0 1-12 12h-64a12 12 0 0 1-12-12V56a12 12 0 0 1 12-12Z"
+      stroke-width="6"
+    />
+
+    <path d="m276 75 18 13-18 13" stroke-width="8" />
+    <path d="M302 103h22" stroke-width="8" />
+  </g>
+</svg>

package/docs/evidence/live-checks-2026-07-19.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-07-19T13:45:14.945Z",
+  "repositoryCommit": "8f8eccdd20272ebb88d0339087fc9cd3828e65c9",
+  "checks": [
+    {
+      "id": "npm",
+      "status": "failed",
+      "detail": "npm registry returned HTTP 404 for loadout-ai@0.3.2"
+    },
+    {
+      "id": "stable-install",
+      "status": "verified",
+      "detail": "isolated Stable flow installed 4 pinned packages and completed state and filesystem rollback assertions"
+    },
+    {
+      "id": "github",
+      "status": "failed",
+      "detail": "GitHub branch protection is not verified for main (HTTP 404)"
+    }
+  ]
+}

package/docs/evidence/live-checks.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/VirajMishra1/loadout/docs/evidence/live-checks.schema.json",
+  "title": "Loadout bounded live-check report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "generatedAt", "repositoryCommit", "checks"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "repositoryCommit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "checks": {
+      "type": "array",
+      "uniqueItems": true,
+      "$comment": "The JSON Schema rejects byte-equivalent duplicate result objects. scripts/check-live-evidence.mjs additionally enforces unique IDs and exact completeness for the checks requested at runtime; cross-item ID uniqueness and a caller-selected exact ID set are parser-only invariants.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "detail"],
+        "properties": {
+          "id": { "enum": ["npm", "stable-install", "github"] },
+          "status": { "enum": ["verified", "failed", "not-verified"] },
+          "detail": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/docs/evidence/readme-claims.json

@@ -0,0 +1,286 @@
+{
+  "schemaVersion": 1,
+  "claims": [
+    {
+      "id": "product.scope",
+      "section": "Introduction",
+      "summary": "Loadout provides a local workflow for discovery, comparison, installation, updates, and rollback.",
+      "evidenceClass": "integration-verified",
+      "status": "bounded",
+      "evidence": [
+        "README.md",
+        "tests/upgrade.test.ts",
+        "tests/snapshot.test.ts"
+      ]
+    },
+    {
+      "id": "catalog.coverage",
+      "section": "Catalog, discovery, and recommendations",
+      "summary": "The bundled catalog exposes generated coverage facts from pinned public records.",
+      "evidenceClass": "structural",
+      "status": "proven",
+      "evidence": [
+        "catalog/packages.json",
+        "src/core/catalog-coverage.ts",
+        "tests/catalog-coverage.test.ts"
+      ]
+    },
+    {
+      "id": "selection.stable",
+      "section": "Choose a profile",
+      "summary": "Stable selection is defined by the checked-in policy and allowlist.",
+      "evidenceClass": "policy-selected",
+      "status": "proven",
+      "evidence": ["src/core/profiles.ts", "tests/profiles.test.ts"]
+    },
+    {
+      "id": "selection.power",
+      "section": "Choose a profile",
+      "summary": "Power selection is defined by the checked-in policy and allowlist.",
+      "evidenceClass": "policy-selected",
+      "status": "proven",
+      "evidence": ["src/core/profiles.ts", "tests/profiles.test.ts"]
+    },
+    {
+      "id": "selection.maximum",
+      "section": "Choose a profile",
+      "summary": "Maximum selection keeps optional components in Loadout's managed library rather than activating every component.",
+      "evidenceClass": "integration-verified",
+      "status": "bounded",
+      "evidence": ["src/core/active-set.ts", "tests/active-set.test.ts"]
+    },
+    {
+      "id": "agents.support",
+      "section": "Adapter compatibility",
+      "summary": "Supported-agent adapters are limited to checked-in definitions and tested filesystem operations.",
+      "evidenceClass": "integration-verified",
+      "status": "bounded",
+      "evidence": [
+        "src/core/adapters.ts",
+        "tests/adapters.test.ts",
+        "tests/adapter-conformance.test.ts"
+      ]
+    },
+    {
+      "id": "platforms.support",
+      "section": "Adapter compatibility",
+      "summary": "Platform support is bounded to tested local filesystem behavior and does not imply native application execution.",
+      "evidenceClass": "platform-verified",
+      "status": "bounded",
+      "evidence": [
+        "docs/FEATURE_TEST_MATRIX.md",
+        "tests/native-filesystem-smoke.test.ts"
+      ]
+    },
+    {
+      "id": "installation.transaction",
+      "section": "Preview, apply, inspect, and roll back",
+      "summary": "Managed installation plans and applies transactional filesystem changes with snapshots.",
+      "evidenceClass": "integration-verified",
+      "status": "proven",
+      "evidence": [
+        "src/core/install.ts",
+        "tests/transaction.test.ts",
+        "tests/install.test.ts"
+      ]
+    },
+    {
+      "id": "updates.preview",
+      "section": "Catalog, discovery, and recommendations",
+      "summary": "Update workflows present a bounded local plan before an explicit apply step.",
+      "evidenceClass": "integration-verified",
+      "status": "proven",
+      "evidence": ["src/core/update.ts", "tests/update.test.ts"]
+    },
+    {
+      "id": "updates.saved-profile",
+      "section": "Catalog, discovery, and recommendations",
+      "summary": "Update evaluates the saved Stable, Power, Maximum, or Custom profile and applies only reviewed, eligible changes after explicit approval.",
+      "evidenceClass": "integration-verified",
+      "status": "proven",
+      "evidence": [
+        "src/core/profile-state.ts",
+        "src/core/update.ts",
+        "tests/profile-state.test.ts",
+        "tests/update.test.ts"
+      ]
+    },
+    {
+      "id": "installation.empty-target-recovery",
+      "section": "State, persistence, and architecture",
+      "summary": "Managed installation treats recursively empty leftover skill directories as unoccupied while retaining collision protection for files and symlinks.",
+      "evidenceClass": "integration-verified",
+      "status": "proven",
+      "evidence": ["src/core/install.ts", "tests/install.test.ts"]
+    },
+    {
+      "id": "rollback.snapshot",
+      "section": "Preview, apply, inspect, and roll back",
+      "summary": "Rollback restores managed snapshot state within Loadout's supported transaction boundary.",
+      "evidenceClass": "integration-verified",
+      "status": "proven",
+      "evidence": [
+        "src/core/snapshot.ts",
+        "tests/snapshot.test.ts",
+        "tests/transaction.test.ts"
+      ]
+    },
+    {
+      "id": "recommendations.evidence",
+      "section": "Catalog, discovery, and recommendations",
+      "summary": "Recommendations expose bounded repository and local evidence rather than universal quality claims.",
+      "evidenceClass": "unit-verified",
+      "status": "bounded",
+      "evidence": ["src/core/recommend.ts", "tests/recommend.test.ts"]
+    },
+    {
+      "id": "trust.stages",
+      "section": "Catalog, discovery, and recommendations",
+      "summary": "Trust-stage labels distinguish evidence without promoting one stage to another.",
+      "evidenceClass": "structural",
+      "status": "proven",
+      "evidence": [
+        "src/core/benchmark-trust.ts",
+        "tests/benchmark-trust.test.ts",
+        "docs/CATALOG_POLICY.md"
+      ]
+    },
+    {
+      "id": "discovery.read-only",
+      "section": "Catalog, discovery, and recommendations",
+      "summary": "Discovery records candidates separately from catalog promotion and installation.",
+      "evidenceClass": "integration-verified",
+      "status": "proven",
+      "evidence": [
+        "src/core/github-discovery.ts",
+        "tests/daily-discovery.test.ts",
+        "tests/review-queue.test.ts"
+      ]
+    },
+    {
+      "id": "credentials.references",
+      "section": "Credentials, MCP, and executable tools",
+      "summary": "Shared configuration stores credential references rather than secret values.",
+      "evidenceClass": "structural",
+      "status": "proven",
+      "evidence": [
+        "src/shared/schemas.ts",
+        "src/shared/types.ts",
+        "tests/credentials.test.ts"
+      ]
+    },
+    {
+      "id": "credentials.separation",
+      "section": "Credentials, MCP, and executable tools",
+      "summary": "Model API access declarations are separated from non-model service credential requirements in setup and MCP recipe output.",
+      "evidenceClass": "unit-verified",
+      "status": "proven",
+      "evidence": [
+        "src/cli.ts",
+        "src/core/mcp-recipes.ts",
+        "tests/cli-help.test.ts",
+        "tests/mcp-recipes.test.ts"
+      ]
+    },
+    {
+      "id": "mcp.configuration",
+      "section": "Credentials, MCP, and executable tools",
+      "summary": "MCP configuration uses explicit plans and keeps credentials outside persisted shared manifests.",
+      "evidenceClass": "integration-verified",
+      "status": "proven",
+      "evidence": ["src/core/mcp.ts", "tests/mcp-config.test.ts"]
+    },
+    {
+      "id": "manifests.portability",
+      "section": "State, persistence, and architecture",
+      "summary": "Loadout manifests are schema-validated portable declarations and do not contain secret values.",
+      "evidenceClass": "structural",
+      "status": "proven",
+      "evidence": [
+        "src/core/manifest.ts",
+        "src/shared/schemas.ts",
+        "tests/manifest.test.ts"
+      ]
+    },
+    {
+      "id": "benchmarks.protocol",
+      "section": "Development and verification",
+      "summary": "Benchmark planning and protocol artifacts do not by themselves prove a source is benchmarked.",
+      "evidenceClass": "structural",
+      "status": "bounded",
+      "evidence": [
+        "docs/EVALUATION_PROTOCOL_V1.md",
+        "src/core/benchmark-campaign.ts",
+        "tests/benchmark-campaign.test.ts"
+      ]
+    },
+    {
+      "id": "dashboard.local",
+      "section": "Current beta limits",
+      "summary": "The dashboard presents local Loadout data and does not establish hosted-service availability.",
+      "evidenceClass": "integration-verified",
+      "status": "bounded",
+      "evidence": ["src/dashboard.ts", "tests/dashboard.test.ts"]
+    },
+    {
+      "id": "uninstall.complete",
+      "section": "Troubleshooting and uninstall",
+      "summary": "Complete uninstall previews and removes Loadout-managed files, runtime tools, scheduled jobs, and state while preserving unmanaged files and blocking drift unless forced.",
+      "evidenceClass": "integration-verified",
+      "status": "bounded",
+      "evidence": [
+        "src/core/uninstall.ts",
+        "src/core/remove.ts",
+        "tests/uninstall.test.ts"
+      ]
+    },
+    {
+      "id": "distribution.npm",
+      "section": "Quickstart",
+      "summary": "npm distribution wording is time-bounded because offline verification cannot prove current registry availability.",
+      "evidenceClass": "live-verified",
+      "status": "bounded",
+      "evidence": [
+        "package.json",
+        "README.md",
+        "docs/evidence/live-checks-2026-07-19.json"
+      ],
+      "externalPrerequisites": ["Current npm registry availability"]
+    },
+    {
+      "id": "release.state",
+      "section": "Quickstart",
+      "summary": "Release and beta wording is bounded to release-review artifacts and is not proof of current public publication.",
+      "evidenceClass": "structural",
+      "status": "bounded",
+      "evidence": [
+        "docs/RELEASE_REVIEW.md",
+        "docs/evidence/live-checks-2026-07-19.json",
+        "package.json"
+      ],
+      "externalPrerequisites": [
+        "Current package publication and release review"
+      ]
+    },
+    {
+      "id": "testing.deterministic",
+      "section": "Development and verification",
+      "summary": "The repository contains deterministic automated tests for supported local behaviors.",
+      "evidenceClass": "unit-verified",
+      "status": "proven",
+      "evidence": [
+        "package.json",
+        "tests/schemas.test.ts",
+        "tests/transaction.test.ts"
+      ]
+    },
+    {
+      "id": "limits.current",
+      "section": "Current beta limits",
+      "summary": "Current limitations are stated explicitly instead of being represented as present capabilities.",
+      "evidenceClass": "structural",
+      "status": "proven",
+      "evidence": ["README.md", "docs/FEATURE_TEST_MATRIX.md"]
+    }
+  ]
+}