Adoption & ecosystem integration

[dligthart]

WordClaw needs a clearer adoption path beyond the current docs-and-source experience.

Why

Low visibility and a thin integration surface limit the feedback loop, examples, and contribution flow.

Goals

• make WordClaw easier to install and deploy
• make WordClaw easier to try from familiar agent frameworks
• provide concrete starter templates that map to the focused product story
• improve release/distribution hygiene so external users can adopt it without reading the whole repo

Candidate slices

• tagged release process with changelog and release notes
• Docker image build and publish to GHCR for one-command deploy
• starter template: LangGraph/LangChain agent using WordClaw MCP
• starter template: auto-publishing blog flow with approval gate
• starter template: paid newsletter/content paywall demo
• OpenAI-compatible tool schema export for MCP tools
• webhook integration examples (for example Vercel deploy on publish)
• docs landing page section for install/deploy/examples

First practical slice

The best first slice is Docker + starter templates:

• publishable Docker image for API runtime
• LangGraph/LangChain MCP starter example
• docs for running both quickly

This gives the project a one-command deployment path plus an agent-framework entry point, which should improve trialability more than a release tag alone.

[dligthart]

Started the first adoption slice and pushed it as 749f2ca.

This adds a production Docker image, a GHCR publish workflow, and docs for container-based deployment.

Included in this slice:

• Dockerfile with a multi-stage build for the API runtime
• docker/entrypoint.sh that runs migrations on startup by default and then starts the server
• .dockerignore for cleaner builds
• docker-compose.yml updated so docker compose --profile app up --build uses the production image flow instead of node:20 + npm install
• .github/workflows/publish-container.yml to publish ghcr.io/dligthart/wordclaw on main, tags, and manual runs
• docs updates in README.md and doc/tutorials/getting-started.md

Validation passed:

• npm run build
• npm run docs:build
• docker compose config

I did not run a full docker build in this environment, so the workflow/image path is config-validated rather than runtime-validated locally.

Next sensible slice is one of:

1. starter template: LangGraph/LangChain agent using the remote MCP endpoint
2. webhook example: trigger Vercel deploy on publish
3. release hygiene: CHANGELOG + version-tag release notes workflow

[dligthart]

Shipped a demo-blog repair slice in .

Changes:

• fixed TypeScript/lint issues in
• added support so the demo is not hardcoded to one API origin
• replaced the default Vite README with actual WordClaw demo-blog setup docs in

Validation:

demo-blog@0.0.0 lint
eslint .

demo-blog@0.0.0 build
tsc -b && vite build

vite v7.3.1 building client environment for production...
transforming...
✓ 3201 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html 0.46 kB │ gzip: 0.29 kB
dist/assets/index-IJ8RYLCx.css 26.29 kB │ gzip: 5.40 kB
dist/assets/index-CXqXMcEF.js 1,149.51 kB │ gzip: 389.01 kB
✓ built in 4.30s

[dligthart]

Shipped a demo-blog repair slice in commit f0166b3.

Changes:

• fixed TypeScript and lint issues in demos/demo-blog/src/App.tsx
• added VITE_WORDCLAW_URL support so the demo is not hardcoded to one API origin
• replaced the default Vite README with actual WordClaw demo-blog setup docs in demos/demo-blog/README.md

Validation:

• cd demos/demo-blog && npm run lint
• cd demos/demo-blog && npm run build

[dligthart]

Shipped a demo-blog runtime fix in commit restore demo blog content loading.

Changes:

• fetches content types with limit=500 so the demo can discover blog schemas even in larger domains
• adds visible empty and error states instead of silently rendering no posts
• fixes the blog seeder to scope schema fallback lookups by domain and refresh demos/demo-blog/.env with both API URL and API key
• adds npm run demo:seed-blog and updates demo docs

Validation:

• cd demos/demo-blog && npm run lint
• cd demos/demo-blog && npm run build
• npm run demo:seed-blog

[dligthart]

Landed the next adoption/demo slice in d0f860c: the demo blog is now a richer multi-page frontend instead of a single-list proof of concept.\n\nWhat changed:\n- expanded the React demo into blog, authors, categories, tags, archive, post detail, and get-started routes\n- replaced the missing typography-plugin dependency path with explicit article-body styling for paragraphs, h1/h2/h3, links, blockquotes, emphasis, strong text, lists, inline code, fenced code blocks, and markdown tables\n- expanded the seeder to create 3 authors and 6 posts with richer editorial markdown bodies and internal demo links\n- updated the demo README so the new routes and supported markdown elements are documented\n\nValidation:\n- cd demos/demo-blog && npm run lint\n- cd demos/demo-blog && npm run build\n- npm run demo:seed-blog\n- verified via the local API that the seeded demo domain now contains 3 authors and 6 posts

[dligthart]

Landed Native Vector RAG support within the demo blog!

• Integrated the SemanticSearch component into the App.tsx header using a sleek popover UI.
• The component talks directly to WordClaw's /api/search/semantic endpoint.
• It displays contextually relevant text snippets based on pgvector similarity scores (Relevance Score) natively calculated by the backend.
• Updated scripts/seed-blog.ts to auto-generate the embeddings in the background on startup when an OPENAI_API_KEY is detected.
• Fixed a chunking bug where raw JSON fields (like coverImage and slug) were bypassing text extraction and polluting the vector space.
• Confirmed the search correctly parses the text, extracts cleaner chunks, and natively surfaces the highest similarity posts.

[dligthart]

Shipped the next adoption slice on main:

• added wordclaw mcp openai-tools to export the live MCP inventory as OpenAI-compatible type: "function" tools
• preserved live MCP names, descriptions, and input schemas rather than introducing a second handwritten contract
• documented the export in the CLI guide and MCP integration guide
• added focused unit coverage for the schema mapper and CLI help surface

Validated locally with:

• npm test -- --run src/cli/lib/openai-tools.test.ts src/cli/lib/help.test.ts src/cli/lib/mcp-client.test.ts
• npm run build
• npm run docs:build
• node dist/cli/index.js mcp openai-tools --raw

I also verified the earlier LangGraph starter slice from the current main history end to end today:

• npx tsx demos/langgraph-mcp-starter/index.ts inspect over stdio
• remote HTTP attach against a temporary local runtime on port 4100 with a known writer key

Issue #167 stays open for the remaining adoption slices: starter templates beyond LangGraph, webhook examples, and release/distribution polish.

[dligthart]

Shipped another #167 adoption slice on main:

• added a Vercel deploy webhook example at demos/vercel-deploy-webhook.ts
• added a matching guide at doc/guides/vercel-deploy-webhook.md and wired it into the docs sidebar
• added reusable helpers for signed WordClaw audit-webhook verification and publish-event filtering
• updated workflow review approvals so publish decisions emit a content_item audit update with status: "published", which makes deploy-on-publish webhook automation work for governed publish paths too
• added regression coverage for both the workflow audit emission and the Vercel webhook helpers

Validated locally with:

• npm test -- --run src/__tests__/workflow.test.ts src/integrations/vercel-publish-webhook.test.ts
• npm run build
• npm run docs:build
• npx tsx demos/vercel-deploy-webhook.ts --help

Issue #167 remains open for the remaining adoption slices: additional starter templates, release/distribution polish, and any broader framework bridges beyond the current LangGraph + OpenAI-tool export path.

[dligthart]

Progress update: several adoption slices from this umbrella are now shipped on main.

Implemented:

• production Docker image path plus GHCR publish workflow and deployment docs
• docs landing-page and quick-start improvements
• LangGraph MCP starter/demo docs
• wordclaw mcp openai-tools for exporting the live MCP tool inventory as OpenAI-compatible function tools
• Vercel deploy webhook example and guide
• framework onboarding docs and provisioning helpers for Codex and OpenClaw
• demo-blog cleanup and seeding/docs improvements

Keeping #167 open for the remaining ecosystem work: additional starter templates, broader framework bridges, and any remaining release/distribution polish.