byline: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm test                                              # unit suite, no network (vitest)
npx vitest run tests/tools.test.ts                    # one file
npx vitest run tests/tools.test.ts -t "schedule"      # one test by name
RUN_INTEGRATION=1 npx vitest run tests/integration/   # live Ghost/WordPress/research APIs; self-skips without a configured site
npm run typecheck                                     # tsc --noEmit, src/ only
npm run build                                         # tsc -> dist/
npm run dev                                           # tsx src/index.ts (MCP server over stdio)
BYLINE_DEBUG=1 byline <cmd>                           # CLI with stack traces

Two entry points, one binary: bin/byline.js dispatches to the CLI when stdin and stdout are a TTY, otherwise to the MCP server. Its Node-version guard must stay free of import, node: and top-level await.

Architecture in one screen

The host model does the thinking; Byline does everything that touches the outside world. A post moves through the MCP tools in src/tools/ in this order: research_topic (optional, src/plugins/research/) → build_writing_brief (src/craft/brief.ts + dimensions.ts, seeded random per-article hook/arc/voice/texture/author-presence) → the host writes HTML → score_draft (src/craft/score.ts, mechanical regex checks; only platform_html, structure and ai_summary_block block) → generate_image(s)/upload_image(s)/find_media/use_media → create_post with write-back diffing. Personas are YAML in ~/.byline/personas/ (src/config/personas.ts; unknown fields are kept as extras and rendered into the brief, never dropped).

Three invariants shape the code more than anything else:

• Brief and scorer share one definition. BANNED, BANNED_CONSTRUCTIONS and THRESHOLDS live in score.ts; brief.ts imports them so what the writer is warned about and what it is marked down for cannot drift.
• HtmlProfile drives platform-specific prose. Ghost's is a constant; WordPress's is resolved per user from unfiltered_html and fails toward restrictive. src/cli/ names no platform or provider; src/craft/ and src/tools/ take platform-specific prose from HtmlProfile rather than branching on the platform, with one documented exception in media-tools.ts.
• Plugins register in one place each: platforms in src/plugins/registry.ts, provider families (images, research) in src/plugins/providers.ts. src/cli/ walks their CredentialField descriptors and names no platform or provider.