Technical Context: API/product knowledge store + tech writer session mode

[tessak22]

Overview

Add a Technical Context system to Quiver — a structured store for API surface, SDK reference, writing rules, and terminology — and a new tech-write session mode that loads both marketing context and technical context automatically. This makes Quiver a full-featured technical content environment: any session can produce API docs, quickstarts, guides, changelogs, or SEO pages with the right context already loaded.

---

Background

Quiver already manages marketing context (ContextVersion) — positioning, ICP, messaging pillars, brand voice, words to avoid. Technical content (API docs, README, changelogs, guides) needs a parallel system: the API surface, SDK method signatures, error codes, writing rules specific to technical content, and terminology (what to say, what never to say).

Adding this as a first-class Quiver data type means:

• Any session gets technical context natively — no external files, no ritual
• The tech-write session mode auto-loads both marketing + technical context in one start
• Technical context is versionable and auditable like marketing context
• Anyone installing Quiver for their own product fills in their API surface via the settings UI — it's portable out of the box

---

What this is NOT

This does not change or archive any external repos. It is an additive feature to Quiver only.

---

Scope

Three sequential pieces:

1. Technical Context data model + MCP tools

Migration — new technical_contexts table:

model TechnicalContext {
  id          String   @id @default(uuid())
  version     Int
  isActive    Boolean  @default(false)
  productName String?

  // API surface
  baseUrl     String?
  authMethod  String?   // "api_key" | "oauth" | "bearer" | "other"
  sdks        Json?     // Array<{ language: string, packageName: string, installCmd: string, repoUrl?: string }>
  endpoints   Json?     // Array<{ name: string, method: string, path: string, description: string, params?: object }>
  errorCodes  Json?     // Array<{ status: number, type: string, description: string, retryable: boolean }>

  // Writing rules
  writingRules  String?  // freeform markdown
  terminology   Json?    // Array<{ use: string, notUse: string }>
  audienceNotes String?

  // SDK patterns reference
  sdkPatterns String?   // canonical code patterns in markdown

  updatedBy     String?
  changeSummary String?
  createdAt     DateTime @default(now())

  @@index([isActive])
  @@map("technical_contexts")
}

New file: lib/db/technical-context.ts

• getActiveTechnicalContext() — returns the active version or null
• getTechnicalContextVersions() — returns all versions ordered by version desc
• createTechnicalContext(data) — creates new version, sets as active, deactivates previous
• getTechnicalContextById(id) — returns single version by ID

New file: mcp/tools/technical-context.ts

Two tools, following the exact same patterns as mcp/tools/context.ts:

quiver:get_technical_context

• Description: "Get the active technical context — API surface, SDK reference, writing rules, and terminology. Load this at the start of any technical content session."
• No required params
• Returns: full active TechnicalContext object, or { message: "No technical context configured" } if none exists
• Error handling: same pattern as get_context

quiver:save_technical_context

• Description: "Create or update the technical context. All fields are optional — only provide fields being updated."
• Input schema: all TechnicalContext fields except id, version, isActive, createdAt — all optional
• Behavior: creates a new version, sets it active, returns the saved record
• Error handling: same pattern as existing context tools

Update mcp/index.ts: register both new tools alongside existing ones.

Tests (__tests__/technical-context.test.ts):

• getActiveTechnicalContext returns null when none exists
• createTechnicalContext creates first version as active
• createTechnicalContext second call creates version 2, deactivates version 1
• MCP tool get_technical_context returns formatted response
• MCP tool save_technical_context saves and returns record
• MCP tool get_technical_context returns No technical context configured when none exists

---

2. Tech writer skills + tech-write session mode

New skills in skills/ directory:

Five new skills, each following the existing skills/*/SKILL.md + references/ pattern:

skills/tech-writing/

• SKILL.md — core technical writing framework (developer-first principle, content type structures, code example checklist, terminology consistency, common fixes). Instructs agent to call quiver:get_technical_context at session start alongside quiver:get_context.

skills/api-docs/

• SKILL.md — framework for writing API endpoint reference pages. Loads tech-writing as foundation skill.

skills/readme-writer/

• SKILL.md — framework for READMEs and quickstarts.

skills/changelog/

• SKILL.md — framework for release notes and changelogs.

skills/api-reviewer/

• SKILL.md — technical accuracy reviewer. Checks code examples against the active technical context (SDK method signatures, param names, error types). Outputs a numbered C/W/S report (Critical / Warning / Suggestion). Uses quiver:get_technical_context as its reference source.

skills/docs-reviewer/

• SKILL.md — style and structure reviewer. Checks against active marketing context (words to avoid, brand voice, ICP targeting) and technical writing standards. Outputs numbered C/W/S report.

All six skills must have:

• Front matter with name: and description: fields matching existing skill format
• description: written to trigger correctly from natural language (see existing skills for pattern)
• No Quiver-specific product references — fully generic and reusable for any API product

New session mode: tech-write

Update lib/ai/session.ts:

• Add tech-write as a valid mode alongside existing five modes
• System prompt for tech-write mode:
  1. Calls quiver:get_context — loads marketing context (voice, ICP, words to avoid)
  2. Calls quiver:get_technical_context — loads API surface, SDK patterns, writing rules
  3. Loads tech-writing skill as the foundation
  4. Opens with: "What type of content are you writing? (quickstart / API reference / guide / changelog / README / SEO comparison page)"
  5. Based on answer, loads the appropriate sub-skill (api-docs, readme-writer, changelog, etc.)
  6. If no technical context is configured, continues with marketing context only and notes the gap

Update app/(app)/sessions/new/page.tsx:

• Add tech-write as a selectable mode in the new session UI
• Label: "Technical Writing"
• Description: "API docs, quickstarts, guides, changelogs, and SEO pages — with your full product context loaded."
• Icon: something appropriate (document/code)

Update PROMPT.md:

• Document tech-write mode alongside existing five modes
• Explain the two-context loading pattern (marketing + technical)
• Document that both api-reviewer and docs-reviewer are available as reviewers within a tech-write session

Tests (__tests__/session-tech-write.test.ts):

• tech-write mode is a valid session mode
• Session initial message for tech-write asks content type question
• tech-write session loads both context types in system prompt
• tech-write session handles missing technical context gracefully (does not throw, notes gap)

---

3. Technical Context settings UI

Update app/(app)/settings/page.tsx:

Add a "Technical Context" tab/section. The existing settings page has multiple sections — add this as a new section following the same component patterns.

Fields (all optional, inline validation where applicable):

Field	Input type	Notes
Product name	Text	e.g. "Tabstack", "Your API"
Base URL	Text	e.g. https://api.example.com/v1/
Auth method	Select	api_key / oauth / bearer / other
SDKs	Repeater	language, package name, install command, repo URL (optional)
Endpoints	Repeater	name, HTTP method, path, description
Error codes	Repeater	status code, error type, description, retryable checkbox
Writing rules	Textarea	Markdown. Placeholder: "E.g. Never say 'scraper'. No em dashes. Lead with developer outcome."
Terminology	Repeater	Two columns: "Use" / "Don't use"
Audience notes	Textarea	Who is this written for?
SDK patterns	Textarea	Canonical code patterns in markdown. Used by api-reviewer for accuracy checks.

Behavior:

• "Save" creates a new version and sets it active (same pattern as marketing context save)
• Show current version number and last updated timestamp
• "View history" link opens a version list modal — same pattern as marketing context history
• If no technical context exists, show an empty state: "No technical context configured. Add your API details to enable technical writing sessions."
• All repeater fields (SDKs, endpoints, error codes, terminology): add/remove rows, no minimum required

No approval/proposal flow — technical context saves directly (no propose step like marketing context has). Technical specs are factual, not positioning decisions.

Tests (__tests__/technical-context-settings.test.ts):

• Settings page renders Technical Context section
• Empty state renders when no context configured
• Save creates new version
• Version number increments on subsequent saves
• History displays previous versions

---

Approval gates

• Before starting piece 2: Piece 1 merged and MCP tools confirmed working via smoke test (mcp/smoke-test.mjs pattern)
• Before starting piece 3: Piece 2 merged and tech-write session mode confirmed functional in local dev
• Before final merge of piece 3: Settings UI tested with a real save/load cycle confirming quiver:get_technical_context returns the saved data correctly

---

Out of scope

• No approval/proposal flow for technical context (saves directly)
• No MCP tools for reading/writing individual endpoints or SDKs separately — the full context object is the unit
• No import from external API spec formats (OpenAPI, etc.) in this issue — can be a follow-on
• No changes to existing skills, session modes, or context system

---

Definition of done

• technical_contexts table migrated
• quiver:get_technical_context and quiver:save_technical_context MCP tools registered and passing tests
• Six new skills in skills/ with correct front matter and no Quiver-specific references
• tech-write session mode available in new session UI, loads both contexts, handles missing technical context gracefully
• Technical Context section in settings: renders, saves, versions, shows history
• All new tests passing
• PROMPT.md updated with tech-write mode documentation
• MCP smoke test passes with new tools