Writing Agent

The writing agent is a single-shot editor pass that reads the current MDX of a page, proposes an improved version, and shows you a diff. Nothing is committed until you approve.

Where to find it

Open any page in the editor. The toolbar (next to Save) gets a new Improve button:

• Free tier: the button shows a lock icon and links to /upgrade?from=writing_agent.

• Pro and above: click Improve → optional instruction → diff preview → Accept or Discard.

Tools the agent uses today

The MVP runs a single LLM pass with a focused editorial system prompt. It:

• Reads the current MDX (full file, frontmatter included)

• Preserves frontmatter, custom MDX components (<Note>, <Tabs>, etc.), and internal links exactly

• Improves clarity, flow, scannability, and grammar

• Returns the revised MDX — never a chat reply, never a summary

If the page is already in good shape the agent returns it unchanged and the diff modal tells you so.

Optional instruction

The instruction box is the steer. Examples that work well:

• "Make this beginner-friendly. Assume the reader has never used our SDK."

• "Tighten — drop redundant sentences and combine the bullet lists where possible."

• "Add a code example for the most common use case."

Leave the instruction empty for a generic editorial pass.

Credits + accounting

A credit is roughly 1,000 tokens (input + output). A typical "improve this page" run on a 500-line MDX file costs 3-8 credits. Every run is logged to the agent_runs table and counts against the org's monthly quota.

The diff modal shows credits used + remaining quota inline.

Accept / Discard

• Accept: the editor buffer is replaced with the proposed MDX. The save indicator goes to Unsaved. Click Save to commit through the existing pages-save flow (your normal git commit).

• Discard: the modal closes and nothing changes.

Both decisions are logged on agent_runs so you can audit acceptance rate later.

Plan availability

What the agent does NOT do (yet)

• Multi-page refactors

• Branch creation + PR opening

• Background re-runs ("keep this page up to date with the spec")

• Custom style guide enforcement

• Image generation

These land in later sprints. This MVP exists to prove the credit-accounting and editorial prompt pipeline.

POST https://api.nookdocs.com/v1/projects/<project_id>/agent/improve
Authorization: Bearer <jwt_or_api_key>
Content-Type: application/json

{
  "pagePath": "/api/authentication",
  "instruction": "Tighten and add a code example for OAuth flow."
}

{
  "runId": "...",
  "originalMdx": "...",
  "proposedMdx": "...",
  "creditsConsumed": 5,
  "inputTokens": 4231,
  "outputTokens": 892,
  "model": "anthropic/claude-sonnet-4.6",
  "quota": { "remaining": 4995, "cap": 5000, "overage": false }
}

PATCH https://api.nookdocs.com/v1/projects/<project_id>/agent/improve
{ "runId": "...", "decision": "accepted" | "rejected" }