TapState documentation

Source for the TapState product documentation published under tapstate.com/docs.

The site is built with Next.js, Fumadocs, MDX, and static export. It serves the human documentation, connector guides, searchable content, llms.txt, llms-full.txt, and page-level Markdown for AI readers.

Requirements

• Node.js 20.9 or later
• npm 10 or later

The repository currently uses Next.js 16 and TypeScript 6. Use the committed package-lock.json for reproducible dependency installation.

Install dependencies

From the repository root:

npm ci

Use npm install only when intentionally changing dependencies and updating the lockfile.

Run locally

npm run dev

Open http://localhost:3000/docs. The root route is the product landing page.

Validate and build

Run the same gates used for documentation changes:

git diff --check
npm run brand:check
npm run types:check
npm run build

npm run types:check regenerates the Fumadocs collections and Next.js route types before running TypeScript. npm run build creates the static site in out/.

When the TapState product repository is available, verify that every bundled catalog connector is published, covered by a current guide, or explicitly deferred:

TAPSTATE_CATALOG_DIR=/path/to/tapstate/core/core-catalog/src/main/resources/catalog \
  npm run connectors:check

Use the same catalog path with npm run connectors:coverage to verify the canonical connector-page structure: profile, role-specific preparation, mode-specific CDC paths, validation scope, limitations, and reference.

When the docs-en migration baseline is available, verify that every independent upstream connector page is migrated, covered by a consolidated guide, or explicitly deferred:

DOCS_EN_CONNECTORS_DIR=/path/to/docs-en/docs/connectors \
  npm run connectors:closure

Preview the production export locally:

npm run preview

Then open http://localhost:3000, unless serve selects another available port.

Content layout

content/docs/
├── overview/       Product introduction, quickstart, use cases, and architecture
├── concepts/       Connections, capture modes, resources, state, and AI concepts
├── connectors/     Connector preparation, creation, limitations, and reference
├── guides/         Cross-connector workflows and troubleshooting
├── reference/      Canonical DSL field and resource reference
└── for-ai/         LLM context and AI-assisted authoring guidance

src/
├── app/            Next.js routes, static metadata, and LLM endpoints
├── components/     Shared MDX and documentation UI components
└── lib/            Fumadocs source loading and Markdown conversion

research/brand/     Non-runtime brand research, concepts, and source assets
research/product-fact-alignment.md
                    Deferred implementation and rebrand verification checklist

Generated routes

• /docs — canonical documentation index
• /docs/<section>/<page> — canonical reader pages
• /llms.txt — compact AI discovery index
• /llms-full.txt — combined canonical documentation context
• /llms.mdx/docs/<page>/content.md — page-level Markdown for AI readers
• /og/docs/<page>/image.png — generated social preview images
• /sitemap.xml — canonical reader-page discovery for search engines
• /robots.txt — crawler policy and sitemap location

Do not edit generated files under out/. Update the MDX source or LLM conversion code and rebuild.

Connector documentation

Use the migrate-tapstate-connector-docs skill when migrating or substantially revising a connector page:

python3 ~/.codex/skills/migrate-tapstate-connector-docs/scripts/audit_connector_doc.py \
  content/docs/connectors/mysql.mdx

Connector IDs, modes, config fields, defaults, and sink capability must come from the current TapState connector catalog. Upstream TapData documentation is a compatibility and preparation baseline, not proof of a TapState UI or runtime feature.

Brand and compatibility identifiers

Use TapState in titles, descriptions, diagrams, and reader-facing product copy.

The current implementation still exposes several compatibility identifiers. Keep them exact in executable examples until the product repository changes the contract:

• CLI binary: tapstate
• resource extension: .tapstate.yml
• resource version: version: tapstate/v1
• workspace environment variable: TAPSTATE_WORKDIR

These are implementation identifiers, not the public product name.

Do not finalize commands, installers, runtime status, or release claims until the latest implementation is committed and rebranded. Use research/product-fact-alignment.md for that later alignment pass.

Deployment

The repository produces a static out/ directory and can be deployed to any static host. For Vercel or Cloudflare Pages, configure:

• Install command: npm ci
• Build command: npm run build
• Output directory: out

Set the site environment at build time. This controls canonical URLs, structured data, llms.txt, robots.txt, and the sitemap.

Deployment	TAPSTATE_SITE_URL	TAPSTATE_SITE_INDEXABLE
Preview	The exact preview origin, such as https://docs-preview.example.com	false
Production	https://tapstate.com	true

Indexing is opt-in: if TAPSTATE_SITE_INDEXABLE is absent, the exported site emits noindex metadata, disallows crawlers, and omits the sitemap. Set both variables in the deployment platform rather than committing them to the repository.

Netlify

The repository includes netlify.toml. It runs npm run build and publishes the static out/ directory; do not configure Netlify to publish dist or add next export to the build script.

During a Netlify build, DEPLOY_PRIME_URL is passed to TAPSTATE_SITE_URL, so canonical links and LLM URLs use the active production, branch, or Deploy Preview origin. Production deploys are indexable; branch deploys and Deploy Previews are not.