coframe.tech — Website Planning Document¶

Status: v1.0 Prepared for: reeeneeee Purpose: Concrete recommendations for standing up coframe.tech as a documentation-and-positioning website during Coframe Core's implementation, with a phased path to a full launch surface at and after v1.0 ship.

Changes from v0.2 (v1.0 publication pass): Document-version references in §2.1 updated to current versions. §4 Status page bullets updated to include the verification-levels-are-informational-in-v1.0 disclosure. Note added on Platform Design's public-facing publication. No structural changes; the Phase 0 calibration remains correct.

1. Scope and intent¶

This document plans the website that will eventually live at coframe.tech. The site has three audiences and three tempos:

Audiences: - Practitioners evaluating Coframe — data engineers, analytics engineers, AI/ML engineers reading the Article and the Manual to assess the framework. - Implementers and contributors — people reading the Platform Design and considering contributing to or extending Coframe. - Decision-makers and researchers — people forming opinions about Coframe for organizational adoption, academic citation, or strategic positioning.

Tempos — the three phases proposed in the conversation that motivated this document:

Phase 0 — Now (before Core implementation begins): documentation-and-positioning website. Static documentation hosting, the Article as centerpiece, basic AI assistant. Goal: claim the domain, make the project legible, gather email addresses.
Phase 1 — During Core implementation: tutorials and getting-started content accumulate as Phase 8 documentation deliverables come online. The AI assistant gets richer as more documentation accumulates. Static showcase examples (without yet being interactive). Goal: feedback loop with early evaluators.
Phase 2 — At or shortly after Core v1.0 ship: interactive playground with role-based UIs, sample datasets, sandboxed AC authoring and querying. The AI agent demo becomes concrete. Goal: conversion tool that moves practitioners from "interesting in theory" to "I see how this works for my data."

The decisions in this document are calibrated for Phase 0. Phase 1 and Phase 2 will need their own planning passes as Coframe Core's implementation progresses.

2. Tooling recommendation¶

2.1 The choice¶

Recommendation: MkDocs with the Material theme.

This is the right choice for Phase 0 because:

It handles the documents you have without conversion work. MkDocs is a markdown-native static site generator. Manual v1.0, Platform Design v1.0, and Article v1.0 are well-structured markdown that drops in essentially as-is.
The Material theme is professional and well-supported. Used by Kubernetes, FastAPI, Pydantic, Hugging Face Transformers, Anthropic's documentation, and many other reference projects. It looks credible to a technical audience without custom design work.
It has excellent built-in features. Full-text search (no external dependency); responsive mobile rendering; navigation that handles deep document trees; code-block highlighting; admonitions (callout boxes); table of contents per page; light/dark mode; print-friendly views.
It's fast and simple to deploy. Static HTML output; no server runtime; deploys to GitHub Pages, Netlify, Vercel, S3, or any static host. Build time for documents this size: under 10 seconds.
It scales to the Phase 1 and Phase 2 needs. Tutorial content, code examples, API reference pages all fit MkDocs naturally. The tooling doesn't need to change as the site grows.

Alternatives considered and rejected:

Docusaurus — more JavaScript-heavy, supports React components inline, has built-in versioned-docs and i18n. Strong choice for sites that need significant JavaScript interactivity in documentation. For Coframe's needs, the additional capability isn't worth the additional complexity. Reconsider for Phase 2 when interactive widgets in documentation become valuable.
Hugo — fastest static site generator, very flexible templating. Better for sites that need significant non-documentation content (blogs, marketing pages). For documentation-heavy Phase 0, MkDocs's documentation-first conventions are a better fit.
Sphinx — Python community standard for technical documentation. Powerful but the reStructuredText format adds friction over markdown. Strong for Python API auto-documentation; less strong for the kind of long-form technical writing that dominates Coframe's documents.
Custom-built — no. Phase 0 doesn't need custom infrastructure; the leverage is in the documents, not the website code.

2.2 Configuration recommendations¶

Material theme configuration choices that matter for Coframe specifically:

Color palette — neutral. The framework is technical and serious; colorful theming would undermine that tone. Recommended: a dark accent color (deep blue or near-black), white background, with a grayscale-leaning palette. Avoid bright colors except for inline links and code-block syntax highlighting.
Typography — system fonts or one well-chosen serif/sans pair. The Material theme defaults are fine. Don't go custom for Phase 0; revisit if a visual identity emerges later.
Navigation — sidebar navigation tree structured by document section. Top-nav for moving between major sections (Article, Manual, Platform Design, etc.). Search prominently placed.
Code blocks — syntax highlighting enabled, line numbers on, copy-to-clipboard button. Coframe documents have substantial code/YAML examples; making them inviting matters.
Admonitions — used judiciously for "Note", "Caveat", "Example" callouts in the Manual. The Material theme handles these elegantly.
Versioning — disabled for Phase 0. Single-version is simpler. When Coframe Core hits v1.0, enable Material's versioned-docs feature to preserve previous version documentation as the framework evolves.

3. Site structure¶

The Phase 0 site should have these major sections, in roughly this order:

Home — landing page; what Coframe is in 30 seconds; links to next steps.
Article — the practitioner's introduction; the most-linked document.
Manual — the Coframe Core Manual; reference specification.
Platform Design — the engineering design document.
Status — what's implemented, what's coming, project roadmap.
About — project background, author bio, contact.
Ask Coframe (Phase 0 stretch goal) — AI assistant page.

3.2 Page-level structure¶

Home page — single-screen positioning. Roughly:

Header: project name, one-sentence tagline, hero call-to-action button to the Article.
A brief paragraph (3-5 sentences) of what the framework is and why it matters.
A small set of "what makes Coframe distinctive" bullets — pulled from the Article's open-operational-space framing.
Links to: Read the Article, Explore the Manual, Follow the Project (status page), Get in touch.
Footer: project metadata, license note, contact pointer.

The home page should be minimal and non-marketing. Coframe's audience is technical; a landing page that reads like marketing copy will be discounted. Three short paragraphs and clear next-step links are enough.

Article — single long page or split into chapters?

Recommendation: single long page. The Article is structured as one continuous argument; splitting it across pages breaks reading flow and makes URL sharing harder. MkDocs' table-of-contents-on-the-right pattern makes long pages navigable. The Article is around 480 lines; rendered, it's a comfortable long read, not an unmanageable wall of text.

Manual — split by chapter, with a single landing page that lists all chapters. The Manual is reference material; readers come for specific chapters, not to read end-to-end. Each chapter as its own page; the landing page is the table of contents with brief summaries of what each chapter covers.

Platform Design — single long page, similar reasoning to the Article. Engineering documents read better when the whole design is in one place rather than fragmented.

A note on the Platform Design's public-facing form. The v1.0 document is publication-ready as-is — the open-questions section (§12) cleanly separates resolved decisions from those legitimately deferred to specific build phases, which a public engineering audience will read as appropriate engineering rigor rather than as unfinished work. No editorial pass needed before publication.

Status page — content described in §4 below.

About page — author bio, project history (brief — when did this start, what motivates it), license information, contact pointers, optional: a "vision" or "research" section that points to deeper-thinking work as it accumulates (the Track 2 work eventually lives here).

3.3 Cross-cutting elements¶

Footer on every page: project metadata, "last updated" date, GitHub link (when there is one), license note, contact link.

"On this page" navigation — Material theme's right-sidebar TOC, automatically generated from headers. Standard.

Breadcrumbs — useful for the Manual where chapters are nested. Material theme handles this.

Search — Material theme's built-in search is good enough for Phase 0. It indexes all content client-side; works offline; no external dependency.

Print stylesheet — Material theme's defaults handle this acceptably. Don't customize for Phase 0.

4. The Status page¶

This deserves its own subsection because it's the page that signals the project is alive and progressing.

The Status page should answer:

What's currently implemented? A simple state list: which packages exist (coframe-core, coframe-connect, coframe-polars, coframe-duckdb, coframe-mcp), what state each is in (specification only / in-progress / functional / production-quality). For Phase 0, all are likely "specification only" with implementation planned.
What's the roadmap? The Phase 8 plan from the Platform Design, summarized in human-friendly form. Eight phases with brief descriptions; rough sequencing; what each phase produces.
What's stable surface vs. informational at v1.0? A short subsection clarifying which v1.0 surfaces are semver-governed (AC YAML format, Frame-QL grammar, Backend protocol, MCP capability surface, etc.) and which are informational-but-documented (currently: AC Verification Levels A / AA / AAA, with stable-surface promotion targeted for v1.x after field experience). This matters for early adopters making integration decisions; the Platform Design's §10 has the full list, but the Status page should surface it directly so evaluators don't have to dig.
Where to engage? GitHub repo when it exists; mailing list / newsletter signup; how to provide feedback; how to follow updates.
Last update — a clear "this status is current as of [date]" stamp. Updated whenever the page changes.

The Status page is also where you can transparently flag what's not yet done. "Coframe Pro is in commercial development on a parallel track; details are not yet public" is more credible than implying everything is imminent.

5. The AI assistant¶

5.1 What it should do¶

The Phase 0 AI assistant has a specific job: answer questions about Coframe, grounded in the project's documentation, without hallucinating about features that don't exist.

Specifically, it should:

Answer "what is Coframe?" / "what's the difference between Coframe Core and Coframe Pro?" / "how does the FD-DAG work?" — questions where the answer is in the documents.
Help users navigate the documentation: "where in the manual is this discussed?" / "is X in Coframe Core or Coframe Pro?"
Decline questions outside scope: implementation timeline, commercial pricing, comparisons to specific competitor products.
Explicitly cite which document and section answered the question, so users can verify.

It should not:

Generate code examples for Coframe APIs that aren't yet implemented.
Speculate about features beyond what's in the documents.
Invent benchmarks, pricing, or timelines.

5.2 Architecture recommendation¶

Recommendation: RAG (Retrieval-Augmented Generation) using Anthropic's Claude API.

Why Claude:

Strong refusal behavior on hallucination. Claude is trained to decline rather than fabricate when grounding is weak. This matters for Coframe specifically — making up features or behaviors would actively damage the framework's credibility. Claude tends toward "I don't see that in the documentation" responses where other models might confidently make something up.
Good at long-context retrieval. Coframe's documents are around 9,000 lines combined. Claude handles long contexts well, which means retrieved chunks can be larger and more contextual.
Good prose quality. Coframe's documentation is written in a particular voice — careful, precise, structured. Claude's outputs tend to match that register better than alternatives.
API is straightforward. No infrastructure overhead beyond an API key.

The basic architecture:

User question
    ↓
[Embedding model — e.g., voyage-3-large or text-embedding-3-large]
    ↓
[Vector database — e.g., Chroma, Qdrant, or Pinecone]
    ↓
Retrieve top-k document chunks (k=5 to 8)
    ↓
[Claude API with retrieved chunks as context]
    ↓
Response with citations to source documents

Implementation specifics:

Document chunking: chunk by section/subsection (not arbitrary token counts). Each chunk has source-document and section-number metadata. The Manual's chapter/section structure makes this clean.
Embeddings: any modern embedding model is sufficient for this corpus size. Voyage's voyage-3-large and OpenAI's text-embedding-3-large are both fine.
Vector store: for Phase 0, Chroma running embedded (no separate service needed) is the simplest path. Switch to Qdrant or similar if scale demands it later.
Prompt engineering: the system prompt should make clear what's in scope ("answer based on the retrieved Coframe documentation") and what's out of scope ("don't speculate about implementation timelines, pricing, or comparisons to specific competitor products"). Include an instruction to cite which document/section the answer comes from.
Citation rendering: when the assistant cites Manual §3.8.5, the rendered output should link directly to the documentation page anchor for that section. Small UI work but high value.

5.3 Deployment options¶

Three reasonable deployment patterns:

Option A: Embedded chat widget on the documentation site. Floating button on every page that opens a chat panel. Common pattern; users discover it organically while reading.

Option B: Dedicated "Ask Coframe" page. Single page with a larger chat interface, optimized for longer conversations. Linked from main navigation.

Option C: Both. Widget for quick questions; dedicated page for deeper sessions.

I'd recommend Option B for Phase 0, escalating to Option C in Phase 1 once the assistant is mature enough that putting it on every page won't surface bad answers. A dedicated page gives users a clear mental model ("I came here to ask about Coframe") and lets the interface be richer than a widget allows.

5.4 Costs¶

Phase 0 estimates, assuming low usage during the early evaluator period:

Claude API: depending on model choice (Sonnet vs Opus) and usage volume, $20-200/month for Phase 0. Most queries will be short; retrieved context is bounded.
Embedding API: one-time cost to embed the corpus (~$1), then negligible incremental cost as the corpus grows.
Vector database: $0 with embedded Chroma; $20-50/month if scaling to a hosted vector DB.
Hosting for the assistant backend: $5-20/month on a small VPS or serverless function platform.

Total expected Phase 0 cost: under $300/month. Probably much less.

5.5 Risk and mitigation¶

The primary risk is the assistant giving wrong answers that damage credibility. Mitigation:

Conservative system prompt. Explicitly instruct Claude to decline rather than guess.
Citation requirement. Every claim should link to a source document section. Users can verify.
Visible "the AI may make mistakes" disclaimer. Standard, but worth having.
Logging for review. Log questions and responses (with appropriate privacy). Periodic review surfaces failure modes — questions where the assistant is consistently weak deserve documentation improvements rather than (only) prompt-tuning.
No code generation in Phase 0. Don't ask the assistant to write Coframe code; the framework doesn't exist yet to verify outputs. Restrict to documentation Q&A and navigation.

6. Hosting and deployment¶

6.1 Recommendation¶

Static site hosting on Netlify or Vercel. Either works; both are excellent.

Why:

Free or near-free for Phase 0 traffic levels.
Automatic HTTPS via Let's Encrypt.
Continuous deployment from GitHub: push to main, site rebuilds and deploys in under a minute.
Custom domain support (coframe.tech connects directly).
Branch previews: every PR gets a preview URL, useful for reviewing documentation changes before they go live.

The AI assistant backend, if it has its own server component (the embedding/retrieval API), can run on Vercel's serverless functions, AWS Lambda, or a small Render/Railway instance. For Phase 0 traffic, free or near-free tiers suffice.

6.2 Domain and DNS¶

The domain coframe.tech is registered at Namecheap. The DNS workflow connects Namecheap (registrar) to your hosting provider (Netlify or Vercel) so traffic to coframe.tech reaches the site.

Concrete setup steps once the GitHub repo and host are configured:

Sign up for Netlify or Vercel; connect to the coframe-website GitHub repository; verify the site builds correctly on the host's default subdomain (e.g., coframe-website.netlify.app).
In the host's dashboard, add coframe.tech and www.coframe.tech as custom domains.
The host provides DNS records to add (typically: an A record or ALIAS for the apex, a CNAME for www, and possibly a TXT record for verification).
In Namecheap's DNS management interface for coframe.tech, add those records.
Wait 5-30 minutes for DNS propagation. Site goes live with HTTPS automatically.

Optional: Cloudflare in front. Adding Cloudflare between Namecheap and the hosting provider gives you free DDoS protection, edge caching, and richer DNS controls. The setup adds maybe 15 minutes: change Namecheap's nameservers to Cloudflare's; add the host's records to Cloudflare DNS instead of Namecheap. Worth doing for any site you expect to gather meaningful traffic; not strictly needed for Phase 0.

SSL is automatic. The hosting provider's Let's Encrypt integration handles SSL certificate provisioning and renewal. Don't buy SSL anywhere.

Email setup. For Phase 0, set up Cloudflare Email Routing (free) to forward hello@coframe.tech (or whichever addresses you want) to your existing personal email. This requires using Cloudflare for DNS (per the optional step above). You can reply, but replies will show your personal email as the sender — fine for Phase 0 correspondence levels.

When email volume justifies it (likely once the project has actual users or commercial inquiries), upgrade to Google Workspace or Fastmail for real send-from-coframe.tech email at $6-12/month per mailbox.

If you don't want to switch DNS to Cloudflare just for email, ImprovMX is an alternative free email-forwarding service that works directly with Namecheap DNS.

6.3 Repository structure¶

Suggest a single repository (coframe-website or similar) with:

coframe-website/
├── docs/
│   ├── index.md                 # home
│   ├── article/
│   │   └── index.md             # the Article
│   ├── manual/
│   │   ├── index.md             # Manual TOC
│   │   ├── chapter-1.md
│   │   ├── chapter-2.md
│   │   └── ...
│   ├── platform-design/
│   │   └── index.md             # Platform Design
│   ├── status.md
│   ├── about.md
│   └── ask/                     # AI assistant (if Option B)
│       └── index.md
├── mkdocs.yml                   # site configuration
├── assistant/                   # AI assistant backend (if separate)
│   ├── api.py
│   ├── retrieval.py
│   └── ...
├── requirements.txt
└── README.md

The repository can live on GitHub (public or private as you choose). Public has the advantage of letting interested practitioners see and contribute to documentation; private is fine if you want more control over what's exposed during Phase 0.

7. Visual identity considerations¶

Phase 0 should not invest heavily in visual identity. The Material theme defaults are professional and credible; that's enough. Specific decisions worth making:

Project name treatment — "Coframe" should be set in a clean sans-serif. No logo for Phase 0; the wordmark in the site header is sufficient.
Favicon — a simple monogram (e.g., a "C" or stylized brackets [C] or similar). Free or near-free to design.
Color — neutral as noted in §2.2. Avoid trying to "brand" the site in Phase 0.
Imagery — none. Coframe's content is text and code; decorative imagery would dilute focus. Diagrams within technical documents are encouraged; marketing imagery is not.

When (if) Coframe gathers a serious user community and Phase 2 is approaching, a visual identity pass becomes worth doing. Phase 0 can defer this entirely.

8. Phasing summary¶

Concrete recommendation for what to build in what order:

Phase 0a (immediate, ~2 weeks)¶

Set up MkDocs with Material theme.
Drop in current documents (Article, Manual, Platform Design).
Configure navigation, search, basic styling.
Deploy to a temporary URL (Netlify subdomain) for validation.
Connect coframe.tech via DNS once the site renders correctly.
Write the home page and About page.
Write the initial Status page.

Output: a working documentation site at coframe.tech, with the documents we have rendered as a navigable, searchable site.

Phase 0b (next ~2-4 weeks)¶

Implement the AI assistant: embedding pipeline, vector store, Claude API integration, dedicated "Ask Coframe" page.
Connect to the documents via a build-time embedding step (re-embed when docs change).
Test thoroughly: ask 30-50 questions covering edge cases; refine system prompt and retrieval until the assistant is reliable.
Add citation rendering.
Soft launch: share the site URL with a small group of trusted technical readers; collect feedback.

Output: complete Phase 0 site with AI assistant.

Phase 1 (during Coframe Core implementation, months 2-7)¶

Add tutorial content as Phase 8 deliverables get drafted (verification levels guide; attestation operational guide; working with time-varying data; working with hierarchical data).
Update Status page as implementation progresses.
Add worked-example ACs (3-5 example ACs as Platform Design Phase 8 plans).
Expand the AI assistant's corpus as documentation grows.

Phase 2 (at and after Coframe Core v1.0)¶

Build the interactive playground (substantial engineering work; separate planning needed).
Production launch.
Switch the site from "in-development" framing to "v1.0 available" framing.

9. Effort estimate¶

For someone competent with web tooling working focused time:

Phase 0a: 30-50 hours of focused work. Real cost: 1-2 weeks of part-time work or a few days of focused full-time work.
Phase 0b (AI assistant): 30-60 hours including testing and refinement. Cost depends heavily on how fussy you are about the assistant's behavior.
Phase 1 content additions: ongoing during Coframe Core implementation; small chunks as content is drafted.
Phase 2 playground: substantial — separate planning needed; rough estimate 2-3 person-months for a polished playground.

If you don't have a frontend engineer on the project, Phase 0a is doable by you over a few weeks of evenings or focused days. Phase 0b is more involved but still tractable; the AI-assistant pattern is well-trodden territory with abundant tutorials and reference implementations.

If you'd rather delegate, contractors familiar with MkDocs and AI-assistant patterns are findable; budget would be roughly $5-10K for Phases 0a and 0b combined, depending on the contractor.

10. Open questions for the next planning pass¶

This document is calibrated for Phase 0. Several decisions deserve their own thinking before Phase 1 and Phase 2:

Email collection / mailing list strategy. Do you want a "follow this project" newsletter from day one? What CRM (if any)? What cadence?
Community infrastructure. GitHub Discussions? A Slack/Discord? Mailing list? When does this start?
Content cadence. Are there blog posts, deeper essays, or position papers planned beyond the documentation? Where do those live? (Track 2 thinking eventually fits here.)
Analytics. What do you want to measure about site usage? Privacy posture?
Internationalization. English-only for v1? Future plans?
Versioned documentation. When Coframe Core v1.0 ships and v1.1 follows, do you want side-by-side documentation? When does versioning get enabled?
Playground architecture (Phase 2). What does the role-based UI look like? What sample datasets ship with it? How is sandbox isolation handled? What's the URL path for sharing playground sessions?

These don't need answers now. They're flagged so they don't get forgotten.

11. What this document doesn't cover¶

To keep scope tight:

Implementation of Coframe Core itself. That's the Platform Design's job.
Trademark and legal review of "Coframe" the brand. Separately tracked.
Commercial strategy for Coframe Pro. Out of scope; that's a different planning conversation.
Detailed contracts for any contractors if you delegate the build. Engage legal counsel separately.
The Track 2 position-paper work. Mentioned where relevant but its own intellectual project.

This document is itself a working draft. Update it as decisions get made and as Phase 1 / Phase 2 thinking sharpens. Versions of this document should track major decisions about the website's evolution.