AgentPress's docs describe a hosted platform plus an npm package, but the published package, the platform sign-in flow, and several documented requirements all fail when followed literally — the install command in the docs cannot actually run the library on Node, and the platform users are told to sign up on has no sign-in UI on this site.
1. Published package ships only raw TypeScript — npx agentpress-sync cannot run on Node (critical)
Location:https://agentpress.netlify.app/docs/getting-started vs. packages/agentpress-nextjs/package.json (v0.1.7)
Problem: Getting Started instructs users to install with any of four package managers:
There is no dist/, no compiled JS, and no build step. The files array publishes only the source .ts/.tsx files, and the bin entry points at ./bin/cli.ts.
Consequence:npx agentpress-sync cannot execute bin/cli.ts on Node — Node has no built-in TypeScript loader, so the documented sync command (the entire premise of the CLI Reference page) is unrunnable for any user not on Bun. The npm/pnpm/yarn install paths advertised in Getting Started silently misrepresent which runtimes are actually supported.
The fix: Either (a) add a real build step (tsup/tsc) that emits ESM/CJS and .d.ts files, then update main/module/types/exports/bin to point at the built output, or (b) explicitly mark the package Bun-only by removing the npm/pnpm/yarn install instructions and adding an engines.bun field plus a prominent compatibility note.
2. Zod version requirement contradicts the package's own peer dependency (critical)
Location:https://agentpress.netlify.app/docs (Requirements), https://agentpress.netlify.app/docs/cli vs.
Problem: The docs root lists "Zod v4+ — Required for schema validation." The CLI Reference repeats it ("Zod v4+ must be installed") and its troubleshooting block tells users to run bun add zod@^4.0.0. But the package itself declares:
"peerDependencies": {
...
"zod": "^3.0.0"
}
A 7-major-version drift between what the docs require and what the package declares.
Consequence: Users who already have zod@^3 (the declared, satisfied peer) follow the docs and bump to v4 and may break other workspace packages pinned to v3. Users who keep Zod 3 satisfy the peer dependency but hit the CLI's "Zod not found" error from the troubleshooting section. There is no way to be simultaneously correct against both the docs and package.json.
The fix: Pick one. If the library actually requires Zod 4, bump peerDependencies.zod to ^4.0.0 and republish. If Zod 3 is genuinely supported, remove the v4+ language from the docs and the CLI's bun add zod@^4.0.0 recommendation.
3. The platform users must sign up for is undocumented and the site's own sign-in page is empty (critical)
The homepage's primary "Get Started" CTA points to /signin, but that route renders only the brand wordmark and a "Back to home" link — no login form, no OAuth buttons, no credential entry. Meanwhile, https://agentpress.ai (a different domain) is referenced exactly once across the seven scraped doc pages with zero context: there is no documentation anywhere on this site for the AgentPress platform itself — no description of project settings, no explanation of where to find AGENTPRESS_SECRET_KEY (the CLI just says "Get this from your project settings"), no definition of "Base URL" (referenced in the ngrok step), no auth model for the cloud, no pricing, no rate limits, no SLA.
Consequence: A developer arriving at the docs cannot complete step one of Getting Started. The homepage CTA is a dead end, the linked-to platform is on a different domain with no documentation, and even after they somehow create a project, the docs never explain what "project settings" looks like, where the secret key lives, or what fields exist beyond "Base URL" and "Project ID." An AI agent asked to set up AgentPress will hallucinate the platform UI because there's nothing to reference.
The fix: Either fix /signin to actually be a sign-in page (or redirect to agentpress.ai), and add a "Platform" section to the docs that screenshots/describes the project dashboard, walks through obtaining AGENTPRESS_SECRET_KEY, defines Base URL, and documents the platform's auth model and any quotas. At minimum, replace the bare "Visit AgentPress" line with a link to a documented onboarding page on the actual platform.
4. Tailwind config snippet uses v3 syntax with no v4 guidance, while the rest of the stack assumes 2025-era versions (significant)
Tailwind v4 (released January 2025) replaced the JS content array with CSS-first @source directives in the global stylesheet. Nothing in the docs acknowledges Tailwind v4; the docs root just lists "Tailwind CSS" with no version pin. Yet the same Requirements list mandates Next.js 15+ and React 19+, the post-2024 stack where v4 is the current default.
Consequence: A user starting a fresh Next.js 15 project today (Tailwind v4 is what create-next-app ships) will follow these instructions, find that tailwind.config.ts doesn't exist or doesn't drive their build, and get an unstyled chat component with no error. The docs never tell v4 users that the equivalent is @source "../node_modules/agentpress-nextjs/**/*.{ts,tsx}"; in the CSS file.
The fix: Either pin a supported Tailwind version explicitly in the Requirements ("Tailwind CSS v3.x") and note v4 incompatibility, or add a parallel v4 example using @source and clarify which syntax to use for which version.
5. The default "AgentPress cloud" endpoint is the documentation site itself (significant)
Location:https://agentpress.netlify.app/docs/api-reference vs. https://agentpress.netlify.app/docs/components
Problem: The Components page advertises the apiEndpoint prop as "Custom API endpoint (defaults to AgentPress cloud)." The API Reference reveals the actual default:
| `apiEndpoint` | string | No | "https://agentpress.netlify.app/api/chat" | Custom API endpoint |
The "cloud" is a Netlify-hosted route on the same domain that serves the marketing/docs site. There is also a separate environment variable NEXT_PUBLIC_AGENTPRESS_API_BASE_URL documented as "Custom API base URL. Only set if self-hosting or using a custom AgentPress instance" — but the relationship between the prop, the env var, and agentpress.ai (the platform domain from Getting Started) is never explained.
Consequence: Production deployments inherit a default that points at a Netlify URL co-located with the docs site. A developer has no signal whether this is a stable production endpoint, a dev-only stub, or whether they should override it for production. The split-brain between agentpress.ai (where projects live), agentpress.netlify.app/api/chat (where chat traffic goes by default), and NEXT_PUBLIC_AGENTPRESS_API_BASE_URL (an undocumented "custom instance") leaves developers guessing about request routing and data residency.
The fix: Either move the production chat endpoint to a stable domain (e.g. api.agentpress.ai) and update the default, or document explicitly that the Netlify URL is the production endpoint and why. Add a short "Architecture" page that clarifies which calls go to which host, where the env var overrides, and how the prop, the env var, and the platform project relate.
6. Agent/discovery surface is broken — dead in-docs link, no llms.txt, no sitemap, GitHub README is unmodified create-next-app boilerplate, copy-paste examples fail (significant)
Problem: Several discovery and machine-readability surfaces fail simultaneously:
The docs index's "Getting Help" section says "1. Check the Troubleshooting guide" — verified 404. (/docs/changelog also 404.)
/llms.txt → 404, /llms-full.txt → 404, /sitemap.xml → 404. There is no machine-readable index for AI agents to crawl.
The CLI Reference's "Output Examples" section shows happy-path and warning output but never documents or links an error response schema for the 📤 Uploading ... to AgentPress upload endpoint — what HTTP status, what JSON body, what auth-failure payload.
The public GitHub repo's README is the unmodified create-next-app template ("This is a Next.js project bootstrapped with create-next-app"), with zero AgentPress-specific content — no architecture overview, no contribution guide, no link back to these docs.
The "Edit this page" GitHub link on /docs/syncing-methods resolves to https://github.com/incogiscool/agentpress/tree/main/src/app/(docs)/docs/src/app/(docs)/docs/syncing-methods/page.mdx — a duplicated src/app/(docs)/docs/ segment that does not exist in the repo, so community edits are blocked.
Examples use TypeScript syntax ((tools: string[]) => void, import type { AuthTokenObject }) inside ```javascript fences, and the auth example imports getUserSession from a non-existent package literally named "auth-provider" with no callout that this is a placeholder.
The Getting Started "First Chat Component" snippet is missing the "use client" directive, even though the same example on the Components page correctly opens with "use client";. AgentpressChat is a streaming chat component with state — pasted into app/page.tsx as written, it triggers a Next.js server-component error.
ChatInput props contradict between pages: the Components page documents only onSubmit and placeholder, while the API Reference declares a third prop disabled?: boolean. Neither page acknowledges the other.
Consequence: AI coding agents (Claude Code, Cursor, Copilot) have no canonical index to crawl, hit a dead troubleshooting link from the docs root, and cannot disambiguate the placeholder auth-provider import from a real package — they will frequently emit npm install auth-provider and produce broken setups. Developers copy-pasting the most-followed page in the docs (Getting Started) will get a server-component crash on first render. Anyone discovering the project via GitHub first sees a create-next-app template.
The fix: (1) Either build the missing /docs/troubleshooting and /docs/changelog pages or remove the links. (2) Generate /llms.txt, /llms-full.txt, and /sitemap.xml. (3) Document the upload endpoint's error response schema in the CLI Reference. (4) Replace the GitHub README with real project content. (5) Fix the editUrl template so the path segment isn't duplicated. (6) Re-tag the example fences as ```tsx and clearly mark auth-provider as a placeholder (e.g. "@your-auth/provider" with a comment). (7) Add "use client"; to the Getting Started snippet. (8) Reconcile ChatInputProps between the Components page and API Reference.
What they do well
Tight type surface. The AgentpressChatProps, Method, and AuthTokenObject types are documented in one place with both a TS interface and a props table — easy for agents to parse.
Concrete CLI output samples. The agentpress-sync happy-path and warning examples include the actual emoji-prefixed log lines, which makes it easy to grep against real CLI output.
Tunneling section is honest. The ngrok walkthrough explicitly warns about URL rotation, free-tier limits, and not committing tunnel URLs — better than most docs at this stage of maturity.
Top 3 recommendations
Ship a real built artifact. Add a tsup/tsc build, point main/module/types/exports/bin at compiled JS, and republish — or explicitly mark the package Bun-only and remove the npm/pnpm/yarn install instructions. Today, npx agentpress-sync cannot execute on Node.
Resolve the Zod version split. Bump peerDependencies.zod to ^4.0.0 to match the documented requirement, or remove the v4+ language from the docs and the CLI troubleshooting step.
Document the platform. Either fix /signin and host onboarding on this site, or clearly point to agentpress.ai and document project settings, secret-key retrieval, base-URL semantics, and the relationship between the prop default, the env var, and the cloud. Until users can complete step 1 of Getting Started, every other doc is hypothetical.