Document the next-release agent registry - #1
Conversation
Make the dev branch the persistent documentation preview target and expose the Fumadocs site through the Vercel project named agents.\n\nConstraint: main remains production and domain configuration is manual.\nRejected: keeping root dev pointed at SDK tests | pnpm run dev should preview the product docs.\nConfidence: high\nScope-risk: narrow\nDirective: Keep preview work on dev and promote reviewed changes to main.\nTested: pnpm check; pnpm lint; pnpm run dev with HTTP smoke.\nNot-tested: authenticated Vercel deployment.
Keep local Next and Fumadocs generated files out of the preview branch.\n\nConstraint: generated development artifacts must not affect release history.\nRejected: committing generated agent instructions | they are recreated by the docs toolchain.\nConfidence: high\nScope-risk: narrow\nDirective: Keep generated docs output ignored.\nTested: pnpm run dev HTTP smoke.\nNot-tested: none.
Exclude local Vercel linkage from repository formatting and keep the docs config minimal.\n\nConstraint: Vercel CLI creates local project metadata during deployment.\nRejected: formatting generated linkage | it is not source code.\nConfidence: high\nScope-risk: narrow\nDirective: Keep generated deployment metadata local.\nTested: pnpm format:check; pnpm docs:build.\nNot-tested: deployed preview until push.
Keep the CLI-created .vercel directory out of the repository.\n\nConstraint: project linkage is machine-local.\nRejected: committing Vercel credentials or metadata | deployment state belongs to Vercel.\nConfidence: high\nScope-risk: narrow\nDirective: Keep .vercel local.\nTested: git status.\nNot-tested: none.
Use the app-local Next build after setting the Vercel root directory to apps/docs.\n\nConstraint: the preview deployment must resolve the monorepo package boundary.\nRejected: copying nested Next output to the repository root | Vercel supports a native root directory.\nConfidence: high\nScope-risk: narrow\nDirective: Keep local Vercel settings aligned with project rootDirectory.\nTested: pnpm format:check; pnpm docs:build.\nNot-tested: deployed preview until push.
Measure documentation traffic through the Vercel-supported Next integration.\n\nConstraint: analytics must be mounted once at the app root.\nRejected: route-level instrumentation | the root layout covers every docs route.\nConfidence: high\nScope-risk: narrow\nDirective: Keep analytics configuration in the docs app only.\nTested: pnpm format:check; pnpm --filter agent-compat-docs typecheck; pnpm docs:build.\nNot-tested: production analytics events.
Configure Tailwind CSS 4 for Fumadocs and add a keyboard skip link so the documentation shell renders with its intended UI and accessible navigation.\n\nConstraint: follow the official Fumadocs Tailwind setup and preserve the existing docs surface.\nRejected: hand-written replacement CSS | the component library already owns the visual system.\nConfidence: high\nScope-risk: moderate\nDirective: Keep the docs app on the supported Webpack path until Turbopack handles native PostCSS modules.\nTested: pnpm format:check; pnpm lint; pnpm --filter agent-compat-docs typecheck; pnpm docs:build; agent-browser live snapshot and screenshot.\nNot-tested: Vercel redeploy.
Close the public documentation gaps around installation, manifests, validation, adapters, CI, and release evidence while keeping the filesystem/runtime boundary explicit.\n\nConstraint: Documentation must reflect the published @jstn-sdk/agents contract and the main/dev deployment split.\nRejected: Expanding the SDK or claiming runtime support for unavailable hosts | this pass is documentation-only and preserves the evidence boundary.\nConfidence: high\nScope-risk: narrow\nDirective: Keep support counts and release evidence synchronized with docs/support-matrix.md.\nTested: docs build, lint, format check, MDX generation, TypeScript check, browser snapshot.\nNot-tested: Authenticated Vercel preview access and host-specific runtime execution.
Ensure the docs route uses Fumadocs' shared MDX components so fenced snippets render with syntax styling and copy actions.\n\nConstraint: Keep code rendering centralized in the existing docs route.\nRejected: Replacing Fumadocs code blocks with a custom renderer | the installed component already provides copy behavior and accessibility.\nConfidence: high\nScope-risk: narrow\nDirective: Preserve the shared MDX component map when changing the docs route.\nTested: docs typecheck, Webpack production build, browser copy-button snapshot.\nNot-tested: Clipboard permission behavior outside the browser session.
Publish the complete 55-target catalog and its MCP boundary while keeping the shipped 41-adapter evidence matrix truthful until runtime registry conformance lands.\n\nConstraint: The supplied next-release target IDs differ from the currently published runtime registry.\nRejected: Renaming or claiming shipped adapters in the current matrix | that would make release evidence inaccurate.\nConfidence: high\nScope-risk: narrow\nDirective: Promote the catalog only after all 55 IDs are implemented and conformance-tested.\nTested: MDX generation, format check, docs typecheck, Webpack production build, browser snapshot.\nNot-tested: Runtime conformance for the 55 next-release targets.
Keep pull request checks active for every change while limiting the main-branch release workflow to package, versioning, and release metadata changes.\n\nConstraint: Documentation and unrelated changes must not publish or create release work.\nRejected: Relying only on semantic-release to no-op | the workflow should be skipped before release execution.\nConfidence: high\nScope-risk: narrow\nDirective: Add release paths when a new publishable package surface is introduced.\nTested: pnpm check, git diff --check.\nNot-tested: GitHub Actions execution until the pull request is opened.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2b5892e1b2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| { | ||
| "framework": "nextjs", | ||
| "installCommand": "pnpm install --frozen-lockfile", | ||
| "buildCommand": "pnpm build", |
There was a problem hiding this comment.
For a Vercel project rooted at this repository, this command runs the root build script, which only executes pnpm --filter @jstn-sdk/agents build and never invokes Next.js or creates apps/docs/.next. Consequently the newly configured deployment cannot produce the documentation site; use the existing pnpm docs:build script or configure apps/docs as the Vercel project root.
Useful? React with 👍 / 👎.
| npm install @JustineDevs/agents --registry=https://npm.pkg.github.com | ||
| ``` | ||
|
|
||
| ## Module formats |
There was a problem hiding this comment.
CommonJS consumers following this section cannot load the package: packages/agents/package.json declares type: "module" and its exports["."] contains only an import condition, with no require or CommonJS artifact. Therefore the documented require("@jstn-sdk/agents") example fails rather than providing the claimed CommonJS entry point; either ship a CJS export or document ESM only.
Useful? React with 👍 / 👎.
Include the existing documentation flow asset in the production docs change.\n\nConstraint: Preserve the supplied binary asset without transformation.\nRejected: Regenerating or editing the image | the requested asset already exists.\nConfidence: high\nScope-risk: narrow\nDirective: Keep documentation assets under public/assets.\nTested: Git status and repository commit validation.\nNot-tested: Visual rendering in the production deployment.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2cc99f5fa4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `skills` | no | Named reusable skills and their instructions. | | ||
| | `workflows` | no | Workflow metadata preserved in generated documents. | | ||
| | `roles` | no | Role metadata preserved in generated documents. | | ||
| | `targets` | no | Application-level target metadata. Explicit compile options take precedence. | |
There was a problem hiding this comment.
When a user sets manifest.targets.enabled or disabled and omits CompileOptions.targets, this wording implies those manifest values influence compilation and are merely overridden by explicit options. In packages/agents/src/compile.js, however, target selection ignores manifest.targets entirely and falls back to environment detection, so the SDK may generate artifacts for detected adapters despite the manifest metadata. Document that this field is only preserved in generated documents, or implement the described precedence.
Useful? React with 👍 / 👎.
Make the published agents package compile typed source into dist while preserving the existing ESM API and conformance behavior.\n\nConstraint: Keep the public @jstn-sdk/agents contract and Node 18 support unchanged.\nRejected: Runtime TypeScript loaders in production or a new test runner | emitted dist files keep execution dependency-free.\nConfidence: high\nScope-risk: moderate\nDirective: Add runtime behavior through typed source and update scripts to consume dist.\nTested: pnpm check, including build, typecheck, 53 tests, 41 adapter conformance cases, matrix check, MDX generation, and knip.\nNot-tested: npm publish of the new dist-only package contents.
Make Vercel build the documentation app, align installation docs with the ESM-only package, and clarify that manifest target metadata is not compile selection.\n\nConstraint: Preserve the current SDK behavior while making deployment and documentation claims exact.\nRejected: Adding a CommonJS build solely for an inaccurate docs example | the package contract is intentionally ESM-only.\nConfidence: high\nScope-risk: narrow\nDirective: Keep Vercel build commands pointed at the docs app and document manifest selection separately from metadata.\nTested: pnpm check and pnpm docs:build; 53 tests and 41 adapter conformance cases passed.\nNot-tested: Post-merge production deployment.
|
Addressed all P1/P2 review findings in commit 093b223:\n\n- P1: vercel.json now runs pnpm docs:build and pnpm docs:dev, so Vercel builds the Fumadocs app.\n- P2: Removed the invalid CommonJS installation example; @jstn-sdk/agents is documented as ESM-only.\n- P2: Clarified that manifest.targets is preserved metadata and does not select compile targets.\n\nVerified with pnpm check and pnpm docs:build. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 093b2236f5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "files": [ | ||
| "src", | ||
| "dist", |
There was a problem hiding this comment.
When pnpm publish:github runs, scripts/publish-github-package.mjs copies only src into its staging directory, while this manifest now includes only dist and points both exported entry points there. The resulting package contains only LICENSE, README.md, and package.json, so every import of @JustineDevs/agents fails; build and copy dist into the stage before publishing.
Useful? React with 👍 / 👎.
| export interface ValidationOptions { | ||
| targets?: string[]; | ||
| } |
There was a problem hiding this comment.
Existing TypeScript consumers importing the previously public ValidateOptions, DetectionResult, CompileResult, ValidationResult, ValidationReport, or RuntimeVerification types stop compiling after this upgrade. index.ts now re-exports only the symbols declared here, but this replacement renames ValidateOptions to ValidationOptions and omits the result types entirely; retain the old names as interfaces or compatibility aliases.
Useful? React with 👍 / 👎.
| "strict": true, | ||
| "noEmit": true, | ||
| "skipLibCheck": true | ||
| "noImplicitAny": false, |
There was a problem hiding this comment.
For TypeScript consumers registering custom adapters or using the testing helper, the emitted declarations now expose parameters such as registerAdapter(adapter) and verifyAdapter(adapter, options) as any, because those implementations remain unannotated and this setting permits implicit any. The previous declarations required Adapter and Manifest, so invalid adapters that were formerly rejected during type checking now compile and fail only at runtime; annotate the exported functions rather than disabling this check.
Useful? React with 👍 / 👎.
Vercel is configured with apps/docs as its project root, so the deployment must invoke that workspace package's build and dev scripts. Constraint: Vercel executes configured commands from the project root Rejected: Root workspace docs:build command | unavailable from the configured docs project root Confidence: high Scope-risk: narrow Directive: Keep Vercel commands aligned with the configured project root Tested: pnpm --dir apps/docs build; git diff --check Not-tested: Remote Vercel deployment after push
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5f2305f75f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "files": [ | ||
| "src", | ||
| "dist", |
There was a problem hiding this comment.
When the documented canonical npm path pnpm publish:agents is run from a clean checkout, dist is absent because it is gitignored and this package has no prepack or prepare script. Running npm pack --dry-run in packages/agents therefore lists only LICENSE, README.md, and package.json, while every entry point references dist; publishing that tarball produces an unusable npm package. Add a packaging lifecycle script that builds dist, or make publish:agents build before publishing.
Useful? React with 👍 / 👎.
1 participant
Summary
Verification
pnpm checkpnpm docs:buildpnpm --filter agent-compat-docs typecheck/docs/agentsand copy controlsRelease policy
This PR contains documentation and workflow policy changes only. CI and fzf checks should run. The release workflow is skipped because no package, changeset, or release metadata path is changed by this PR.