Smolify

Docs get stale. AI answers guess. Smolify makes both show their work.

Smolify turns an API repository into reviewed documentation for people and commit-pinned evidence for coding agents—then shows you the complete Git diff before anything goes live.

Codex reads the implementation on your device—routes, schemas, authentication, middleware, tests, and examples—then writes a portable Markdown bundle. You review the complete diff. Smolify validates and publishes it only after you approve.

Tiny setup. Serious docs.

Try Smolify · Browse the Pawprint demo · Explore a large repository · See the benchmark · Architecture · Onboarding walkthrough

npx -y smolify --agent codex
codex mcp login smolify # only for private docs or writes

Then open the API repository in Codex and ask:

Use $smolify-api-docs to document this API. Reconcile the implementation with
routes, schemas, authentication, tests, and examples. Generate and validate the
bundle, show me the complete diff, and stop before publishing.

1. Codex reads the real implementation locally. Smolify does not need the raw private repository.
2. It generates .smolify/smolify.bundle.json. Pages contain safe Markdown and machine-readable source provenance.
3. You review the complete Git diff. Nothing publishes during generation.
4. Smolify validates and atomically publishes the approved bundle. OAuth is required for private reads and every write.
5. People browse it; agents search it. Both use the same deployment.

Smolify never executes generated MDX or arbitrary JSX. Hosted retrieval uses bounded FTS5/BM25 and structural source evidence—not embeddings or a separate hosted answer model. The connected coding agent performs the final synthesis.

• Original documentation UI built with Next.js, safe Markdown, and sanitized HTML
• Project subdomains, custom domains, and immutable deployment history
• Public discovery with separate provenance and community-review signals

• Anonymous public discovery, search, bounded context, and page reads over MCP
• Exact identifiers plus commit-pinned definitions, callers, callees, and connector paths for eligible public imports
• Agent-side synthesis without embeddings or a hosted answer model
• Authenticated ratings and complete-bundle improvement proposals

• Local-first repository analysis and Git-reviewable portable bundles
• OAuth 2.1, project-scoped publish credentials, and owner-only acceptance
• Tenant-scoped D1 metadata/search and immutable R2 artifacts
• Bounded GitHub import, private ZIP import, CI SDK, and OpenNext deployment

In the branch-local live parity suite, on a pinned July 19, 2026 vercel/next.js canary snapshot, Smolify's bounded retrieval found the implementation evidence needed for a segment-cache navigation trace:

Branch-local run on vercel/next.js commit 0491db047b8f9c4a5f9d0285ad9ed514bb134873 (July 19, 2026). One audited architecture task, not a universal answer-quality comparison; exact labels, retrieval-path scope, and limits follow.

Read the scorecard · Inspect the full methodology and comparison · npm run test:retrieval-parity

This measures evidence retrieval for one audited architecture task—not universal answer-quality superiority over DeepWiki or CodeDB. The recorded public deployment predates these relationship tools; reproducing them through the hosted MCP requires a fresh import and deployment.

See docs/architecture.md for the system boundaries and walkthrough.md for the user-device onboarding, GitHub credential decision, bundle review, and indexing sequence. The short version is:

API repository
  ├─ GitHub URL or bounded ZIP → instant deterministic docs scaffold
  └─ Codex + Smolify skill → reviewed .smolify/smolify.bundle.json
       └─ OAuth MCP
            ├─ owner: publish_docs
            └─ GPT-5.6 community: rate_docs / propose_doc_improvement
                 └─ owner preview + hash-gated acceptance
                      └─ D1 metadata/search + immutable R2 bundles

Smolify is an open-source, multi-tenant Next.js application built for OpenAI Build Week with GPT-5.6 and Codex. It uses an original renderer—not Fumadocs—and runs on Cloudflare through OpenNext. The remote MCP authenticates, searches, publishes, rates, and stores proposals, but only an owner can activate one.

The MCP's build_docs_context tool follows the same evidence-first shape as CodeDB: exact identifiers, focused lexical facets, low-value-page penalties, de-duplication, then bounded packing. Eligible public imports also use exact source-page paths as hints for a bounded pinned-tree symbol resolver. inspect_public_symbols follows relative imports and returns value-free exact definitions, scoped callers/callees, and short connector paths across requested symbols. The graph and excerpts share one hard serialized budget. When an implementation detail is genuinely necessary, read_public_source can fetch at most 200 explicit lines from the immutable commit of an eligible public GitHub import. Smolify does not persist that body, and the tool is unavailable for private repositories and ZIP uploads.

The reproducible benchmark records the MCP trace, DeepWiki comparison, CodeDB design comparison, executable gates, and limits of the claim.

The SDK accepts an async token provider, so an OAuth client can refresh tokens without teaching the API client how credentials are stored:

import { SmolifyClient } from "./sdk";

const smolify = new SmolifyClient({
  accessToken: () => oauthSession.getAccessToken(),
});

await smolify.publish("pawprint", bundle);
const hits = await smolify.search("pawprint", "createUserById 409");
const page = await smolify.getPage("pawprint", hits.results[0].slug, {
  length: 12_000,
});

Requirements: Node.js 20+ and npm.

npm install
cp .dev.vars.example .dev.vars
# Replace BETTER_AUTH_SECRET with a random value of at least 32 characters.
npm run db:migrate:local
npm run preview

Open:

• Landing page: http://localhost:8787
• Generated docs demo: http://localhost:8787/pawprint/introduction
• Authentication: http://localhost:8787/login
• Public repository gallery: http://localhost:8787/explore

From the dashboard, choose Import a repository:

• Paste a public GitHub repository root URL. Smolify reads a bounded tree plus up to 30,000 supported text paths, a balanced set of first-party guides, and representative app/package/extension READMEs. It also analyzes up to 96 priority-plus-breadth public source files into declaration, import, and call-relationship metadata with commit-pinned links. Imported guide content is capped at 8 MB, public source analysis at 2 MB, and both are fetched in bounded batches.
• Upload a ZIP for a private repository. ZIPs are limited to 12 MB compressed, 30 MB expanded, 4,000 entries, and supported text files. Source is analyzed in memory; only the generated Markdown bundle and source paths are retained.
• Choose Public to list the page in Explore and accept community agent reviews, or Private to require workspace membership everywhere.

The instant scaffold includes the README introduction, package-derived setup, source-grounded guide pages, public symbol/call metadata when eligible, and chunked file-index pages searchable through exact identifier matching and D1 FTS5/BM25. Search responses expose confidence, fallback use, identifier coverage, and source paths. The scaffold deliberately avoids inventing behavior. Run the Codex skill in the actual repository to turn it into reviewed API documentation.

Production: https://app.smol.ly. The large-repository fixture is https://app.smol.ly/explore/openclaw.

GitHub OAuth is optional. If enabled, add its client ID and secret to .dev.vars and register this callback:

http://localhost:8787/api/auth/callback/github
https://app.smol.ly/api/auth/callback/github

Authenticated GitHub imports use the signed-in user's API quota. A GITHUB_TOKEN Worker secret is an optional shared fallback for server-side imports, but per-user OAuth avoids putting every import on one account's rate limit.

Smolify shows independent signals instead of collapsing them into a vague "safe" badge:

• Official source means the repository is directly owned by a curated company or standards-body GitHub organization. The registry is keyed by GitHub's immutable numeric owner ID, so a renamed or lookalike account does not inherit the badge.
• Community reviewed requires ratings from ten independent identities with GitHub or verified-email assurance. One account can contribute at most one review per project.
• Neither signal is a security audit. Official provenance identifies where the source came from; community review describes the generated documentation.

Public repository discovery, structure, search, and page reads need no account. OAuth starts only when an agent needs private docs or a write tool; no API key is pasted into chat or stored in the repository.

The cross-agent installer writes the additive smolify entry to ~/.mcpconfig.json, syncs detected agent configs, and installs the shared skill at ~/.agents/skills/smolify-api-docs:

npx -y smolify

Or install it globally. The npm postinstall follows CodeDB's auto-registration experience: it detects installed agents, adds only the smolify entry, installs the shared skill, and verifies the hosted MCP handshake.

npm install -g smolify
smolify doctor

Authorize Codex only when you want to contribute, read a private project, or publish:

codex mcp login smolify

The smolify command configures the MCP and installs the shared skill; smoly remains an alias for existing installs. Unlike CodeDB, Smolify needs no local native binary: agents connect directly to the hosted HTTP MCP so OAuth remains client-native. Manual alternatives are available for troubleshooting and local skill development:

codex mcp add smolify --url https://app.smol.ly/mcp

Install the smolify-api-docs skill from
https://github.com/justrach/smolify/tree/main/skills/smolify-api-docs
into this repository.

npx degit justrach/smolify/skills/smolify-api-docs .agents/skills/smolify-api-docs

mkdir -p /path/to/api/.agents/skills
cp -R skills/smolify-api-docs /path/to/api/.agents/skills/smolify-api-docs

After review, ask Codex to publish with the authenticated MCP. For headless CI, set SMOLIFY_PROJECT and SMOLIFY_PUBLISH_TOKEN and use the skill's publishing script instead.

The skill never prints a token.

Any agent can call discover_public_projects, read_docs_structure, search_docs, build_docs_context, get_doc_page, and—when the import is an eligible public GitHub snapshot—resolve_public_symbols, inspect_public_symbols, and read_public_source. An authenticated GPT-5.6 agent can then call rate_docs. A complete improvement can be submitted with propose_doc_improvement; this stores an immutable pending bundle and does not change the live docs. The owner must preview the complete bundle and send its SHA-256 review hash before Accept and publish is enabled.

npm test
npm run typecheck
npm run lint
npm run build
npm run cf:build
npm run preview             # in one terminal
npm run test:e2e:mcp        # in another terminal
npm run test:e2e:community  # public/private import + contribution review gate

npx wrangler login
npx wrangler d1 create smolify-db
npx wrangler r2 bucket create smolify-docs
npx wrangler secret put BETTER_AUTH_SECRET
npm run db:migrate:remote
npm run deploy

npx wrangler secret put CLOUDFLARE_API_TOKEN

The README hero and product UI use the same Milk, Ink, Smol lime, Periwinkle, Mint, Line, and restrained Coral palette. Voice, tokens, and usage rules live in docs/brand.md; reusable assets live in public/brand.

MIT. See LICENSE.