JustineDevs · JustineDevs · Aug 22, 2026 · Aug 22, 2026 · Aug 22, 2026 · Aug 22, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -4,6 +4,13 @@ on:
   workflow_dispatch:
   push:
     branches: [main]
+    paths:
+      - "packages/agents/**"
+      - ".changeset/**"
+      - ".releaserc.json"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "scripts/publish-github-package.mjs"
 
 permissions:
   contents: write

diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,8 @@ node_modules/
 apps/docs/.next/
 apps/docs/.source/
 apps/docs/tsconfig.tsbuildinfo
+apps/docs/AGENTS.md
+apps/docs/CLAUDE.md
 dist/
 coverage/
 .pnpm-store/
@@ -50,3 +52,4 @@ env/
 # Temporary verification sandboxes
 agent-compat-*/
 release/
+.vercel
diff --git a/.knip.json b/.knip.json
@@ -6,6 +6,7 @@
     "@semantic-release/release-notes-generator",
     "@trpc/client",
     "@trpc/server",
-    "zod"
+    "zod",
+    "portless"
   ]
 }
diff --git a/README.md b/README.md
@@ -206,7 +206,7 @@ Contributions are welcome — especially new adapters.
 ### Adding an Adapter
 
 1. Fork the repository
-2. Add an adapter definition to `packages/agents/src/adapters/index.js`:
+2. Add an adapter definition to `packages/agents/src/adapters/index.ts`:
 
 ```js
 const myToolAdapter = {

diff --git a/apps/docs/app/docs/[[...slug]]/page.tsx b/apps/docs/app/docs/[[...slug]]/page.tsx
@@ -4,6 +4,7 @@ import {
   DocsPage,
   DocsTitle,
 } from "fumadocs-ui/page";
+import mdxComponents from "fumadocs-ui/mdx";
 import { notFound } from "next/navigation";
 import { source } from "@/lib/source";
 
@@ -20,7 +21,7 @@ export default async function Page(props: PageProps) {
       <DocsTitle>{page.data.title}</DocsTitle>
       <DocsDescription>{page.data.description}</DocsDescription>
       <DocsBody>
-        <MDX />
+        <MDX components={mdxComponents} />
       </DocsBody>
     </DocsPage>
   );

diff --git a/apps/docs/app/globals.css b/apps/docs/app/globals.css
@@ -0,0 +1,3 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";
diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx
@@ -1,7 +1,7 @@
 import type { Metadata } from "next";
+import { Analytics } from "@vercel/analytics/next";
 import { RootProvider } from "fumadocs-ui/provider/next";
-import "fumadocs-ui/css/neutral.css";
-import "fumadocs-ui/css/preset.css";
+import "./globals.css";
 
 export const metadata: Metadata = {
   metadataBase: new URL("https://agents-compat.jstn.site"),
@@ -20,8 +20,15 @@ export default function RootLayout({
 }) {
   return (
     <html lang="en" suppressHydrationWarning>
-      <body>
+      <body className="flex min-h-screen flex-col">
+        <a
+          href="#nd-page"
+          className="sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4 focus:z-50 focus:rounded-md focus:bg-fd-popover focus:px-3 focus:py-2 focus:text-fd-popover-foreground"
+        >
+          Skip to content
+        </a>
         <RootProvider>{children}</RootProvider>
+        <Analytics />
       </body>
     </html>
   );

diff --git a/apps/docs/content/docs/adapters.mdx b/apps/docs/content/docs/adapters.mdx
@@ -0,0 +1,54 @@
+---
+title: Custom adapters
+description: Extend the registry without coupling your tool to Meta-Architect.
+---
+
+Adapters describe a concrete product surface. Registering one changes the
+current process registry only; it does not install a vendor runtime.
+
+```ts
+import { Agents } from "@jstn-sdk/agents";
+
+Agents.register({
+  id: "my-tool",
+  vendor: "my-company",
+  product: "my-tool",
+  surface: "cli",
+  support: "portable",
+  verification: { contract: "verified", runtime: "unverified" },
+  signals: [{ type: "file", path: "MY-TOOL.md" }],
+  outputs: [{ path: "MY-TOOL.md", format: "document" }],
+  capabilities: {
+    instructions: true,
+    skills: false,
+    mcp: false,
+  },
+});
+```
+
+## Adapter contract
+
+| Field | Purpose |
+| --- | --- |
+| `id` | Unique surface identifier used by `targets`. |
+| `vendor`, `product`, `surface` | Human-readable taxonomy metadata. |
+| `signals` | Repository files or directories used for detection. |
+| `outputs` | Relative files generated and validated for the surface. |
+| `skillRoot` | Optional directory for generated `SKILL.md` files. |
+| `capabilities` | Declared native or portable feature support. |
+| `support` | `native`, `portable`, or `experimental`. |
+| `verification` | Contract and runtime evidence boundary. |
+
+Every output path is resolved inside the compile root. Unsafe traversal and
+symlinked writes are rejected.
+
+## Registry helpers
+
+```ts
+Agents.list();
+Agents.get("cursor");
+Agents.reset();
+```
+
+Use `reset()` in isolated tests when you need to restore the built-in registry
+before registering test adapters.
diff --git a/apps/docs/content/docs/agents.mdx b/apps/docs/content/docs/agents.mdx
@@ -0,0 +1,130 @@
+---
+title: Agent registry
+description: The 55-target registry planned for the next SDK release.
+---
+
+The next registry release defines **55 agent targets**, representing **54
+vendors** and **53 vendor families**. `universal` is a fallback target, not a
+vendor. `trae` and `trae-cn` share one vendor skill directory.
+
+This page is the next-release catalog. The currently published package remains
+covered by the [current support matrix](/docs/support-matrix) until these target
+IDs are included in the runtime registry and pass conformance checks.
+
+## Registry layers
+
+| Layer | Count | Contract |
+| --- | ---: | --- |
+| Universal targets | 15 | Read `.agents/skills` directly. |
+| Non-universal targets | 40 | Receive skill fanout into the target directory. |
+| Total target entries | 55 | Includes the `universal` fallback. |
+| Distinct vendors | 54 | Excludes the `universal` pseudo-target. |
+| Vendor families | 53 | `trae` and `trae-cn` share a directory. |
+
+## Universal targets
+
+These targets consume the canonical `.agents/skills` directory directly:
+
+```text
+codex
+opencode
+cursor
+amp
+cline
+gemini-cli
+github-copilot
+antigravity
+deepagents
+dexto
+firebender
+kimi-cli
+warp
+replit
+universal
+```
+
+## Non-universal targets
+
+These targets require symlink or copy fanout into their native skill directory:
+
+```text
+claude-code
+windsurf
+goose
+augment
+aider-desk
+continue
+roo
+kiro-cli
+junie
+devin
+openhands
+cortex
+crush
+forgecode
+bob
+codebuddy
+codemaker
+codestudio
+command-code
+codearts-agent
+droid
+hermes-agent
+iflow-cli
+kilo
+kode
+mcpjam
+mistral-vibe
+mux
+neovate
+openclaw
+pi
+pochi
+adal
+qoder
+qwen-code
+rovodev
+tabnine-cli
+trae
+trae-cn
+zencoder
+```
+
+## MCP boundary
+
+Only four targets receive native MCP configuration injection through the
+Universal Plugin Broker:
+
+```text
+claude-code
+antigravity
+cursor
+codex
+```
+
+All other targets receive the `.agents/skills` context payload layer. This
+distinction is intentional: skill fanout is portable, while MCP configuration
+is host-specific and must not be claimed where the native contract is absent.
+
+## Support guarantee
+
+Each next-release target must provide:
+
+- Detection with a stable target ID.
+- Canonical manifest compilation.
+- Portable `.agents/skills` output or native skill fanout.
+- A capability report that identifies MCP support.
+- Filesystem conformance validation.
+- Explicit unsupported-feature warnings.
+
+The registry count is not a claim that every target has identical native
+features. Native MCP support is limited to the four targets above; all other
+targets use the portable context payload until their native contract is
+verified.
+
+## Release gate
+
+The next registry becomes a shipped support claim only when the target IDs are
+present in the runtime registry, the support matrix is regenerated, and the
+conformance suite passes for all 55 entries. Until then, use the current
+published [41-adapter matrix](/docs/support-matrix) for release evidence.
diff --git a/apps/docs/content/docs/api.mdx b/apps/docs/content/docs/api.mdx
@@ -11,6 +11,10 @@ Returns detected adapter surfaces ordered by confidence.
 const environments = await Agents.detect('./project');
 ```
 
+When no environment signal is found, detection returns the portable `generic`
+adapter with low confidence. Detection is repository-based and does not require
+vendor binaries.
+
 ## `Agents.compile(manifest, options)`
 
 Compiles the canonical manifest for selected adapter IDs and writes native or portable artifacts.
@@ -23,7 +27,10 @@ const result = await Agents.compile(manifest, {
 });
 ```
 
-The result includes generated files, warnings, and target-specific errors.
+With no `targets`, the SDK compiles for adapters detected under `output`.
+`dryRun: true` returns the planned files without writing. The result includes
+`targets`, generated files, `created`, `updated`, `skipped`, warnings, and
+target-specific errors.
 
 ## `Agents.validate(root)`
 
@@ -34,6 +41,9 @@ const report = await Agents.validate('./project');
 if (!report.valid) throw new Error('Agent artifacts need attention');
 ```
 
+Pass `{ targets: ['cursor'] }` to validate only selected adapters. Without
+targets, validation uses detected adapters.
+
 ## Adapter registry
 
 Register a custom adapter without importing Meta-Architect:
@@ -42,3 +52,6 @@ Register a custom adapter without importing Meta-Architect:
 Agents.register(myAdapter);
 const adapters = Agents.list();
 ```
+
+Use `Agents.get(id)` to inspect one adapter and `Agents.reset()` to restore the
+built-in registry in a test process.
diff --git a/apps/docs/content/docs/ci.mdx b/apps/docs/content/docs/ci.mdx
@@ -0,0 +1,44 @@
+---
+title: CI and release checks
+description: Add deterministic SDK and documentation checks to automation.
+---
+
+The repository's production checks are intentionally deterministic:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+pnpm lint
+```
+
+The SDK package checks can be run independently:
+
+```bash
+pnpm --filter @jstn-sdk/agents build
+pnpm --filter @jstn-sdk/agents typecheck
+pnpm --filter @jstn-sdk/agents test
+pnpm --filter @jstn-sdk/agents verify
+```
+
+## Validate a project in CI
+
+```ts
+import { Agents } from "@jstn-sdk/agents";
+
+const report = await Agents.validate(process.cwd());
+if (!report.valid) {
+  console.error(JSON.stringify(report, null, 2));
+  process.exit(1);
+}
+```
+
+## What the checks prove
+
+- `typecheck` proves the public declarations remain internally consistent.
+- `test` covers API behavior and safety regressions.
+- `verify` runs compile/write/read/validate conformance in temporary projects.
+- `matrix:check` prevents the support matrix from drifting from the registry.
+- `docs:build` proves the official documentation site can be deployed.
+
+Filesystem conformance is separate from live vendor runtime verification. See
+the [support matrix](/docs/support-matrix) for the current evidence boundary.
diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx
@@ -11,6 +11,9 @@ import { Cards, Card } from 'fumadocs-ui/components/card';
 
 <Cards>
   <Card title="Quickstart" href="/docs/quickstart" description="Install the package and compile your first manifest." />
+  <Card title="Installation" href="/docs/installation" description="Set up npm, pnpm, or the GitHub Packages mirror." />
+  <Card title="Manifest reference" href="/docs/manifest" description="Define the canonical project contract." />
+  <Card title="Agent registry" href="/docs/agents" description="Review the 55-target registry planned for the next release." />
   <Card title="API reference" href="/docs/api" description="Use detection, compilation, validation, and the adapter registry." />
   <Card title="Support matrix" href="/docs/support-matrix" description="See every registered adapter, support level, and capability." />
 </Cards>