Hermes3000 Writing

Overview

Use Hermes3000 when the user wants a durable long-form writing project managed in the writing portal, not just a one-off draft in chat. Hermes3000 stores book structure, chapter content, consistency memory, timeline data, stats, and exports.

For endpoint details, request shapes, and examples, read references/api-workflow.md before making live API calls.

Secret Refs

The bundled helper sends all live Hermes3000 calls through the HybridClaw gateway proxy, matching the Salesforce skill pattern. Login credentials are sent as <secret:NAME> placeholders; the gateway resolves them server-side, captures the returned Hermes3000 JWT into HERMES3000_JWT, and returns only a capture confirmation. The JWT does not enter the agent context.

Never call Hermes3000 with curl or a raw Authorization: Bearer ... header. Use node skills/hermes3000-writing/scripts/hermes3000.cjs ... run ... for live calls so the gateway injects and captures secrets server-side. Run these helper commands exactly as documented. Do not add Node permission flags such as --experimental-permission, and do not rewrite skills/... paths to /workspace/skills/...; the helper needs runtime-provided gateway access for secret resolution.

Cloud and chat/TUI users may not have a terminal. Only ask the user to set secrets with chat/TUI secret commands; do not ask them to run node, curl, or hybridclaw shell commands. If HERMES3000_JWT is missing or blocked, run auth.login yourself through the helper. The helper does not prompt for email or password; it resolves HERMES3000_EMAIL and HERMES3000_PASSWORD from the gateway secret store.

Ask the user to set the login inputs once through browser admin first:

1. Browser admin: open the active HybridClaw admin URL ending in /admin/secrets and set HERMES3000_EMAIL and HERMES3000_PASSWORD.
2. Browser /chat or TUI fallback:

/secret set HERMES3000_EMAIL you@example.com
/secret set HERMES3000_PASSWORD <password>

3. Local console fallback:

hybridclaw secret set HERMES3000_EMAIL you@example.com
hybridclaw secret set HERMES3000_PASSWORD '<password>'

Then the agent, not the user, captures the JWT through the gateway:

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run auth.login

On success, the gateway stores HERMES3000_JWT. Subsequent helper operations set bearerSecretName: "HERMES3000_JWT" internally so the gateway injects the bearer token server-side.

Operating Rules

1. Preserve author control. Ask for or infer the manuscript premise, audience, language, target length, genre or content type, tone, and export format before creating or replacing durable portal content.
2. Treat credentials and JWTs as secrets. Authenticate through the active runtime's secret or credential mechanism when available. Do not print tokens, paste passwords into chat, or store credentials in project files.
3. Prefer the synchronous generation endpoint for agents: POST /ai/generate-text. Use streaming only when the active runtime has a clear SSE reader and the user needs progress output.
4. Save every accepted chapter draft with POST /books/{id}/content, then build consistency memory with POST /consistency/chapter-summary before writing the next chapter.
5. Use stable chapter UUIDs. When AI-generated chapters do not include id, generate UUID v4 values before saving the chapters structure.
6. Keep portal state coherent. Update plot, characters, style, and chapters before generating chapter prose; update story progress after summaries with POST /consistency/update-story.
7. Do not overwrite an existing book, chapter, structure element, or content block unless the user explicitly asks for replacement. Fetch current state first when editing an existing project.

Project Shape

Choose the Hermes3000 bookType from the user's goal:

• prose: novels, novellas, fiction series, narrative long reads.
• nonfiction: nonfiction books, educational material, manuals, essays.
• whitepaper: short-form whitepapers, reports, thought-leadership papers.

Represent structure as:

• plot: Markdown outline of the argument, storyline, or thesis.
• characters: Markdown profiles for fiction characters, or key people, personas, stakeholders, examples, and cited experts for nonfiction.
• style: Markdown writing rules: language, voice, perspective, reading level, terminology, citation stance, formatting preferences, and banned patterns.
• places_things: Markdown world-building, concepts, definitions, datasets, products, organizations, or repeated motifs.
• chapters: Array of {id, title, summary} objects.

Workflow

1. List or authenticate through the helper. If a live call fails because HERMES3000_JWT is missing or blocked, run run auth.login yourself. If login fails because HERMES3000_EMAIL or HERMES3000_PASSWORD is missing, ask the user to set those two secrets with /secret set .... Never ask the user to run terminal commands and never ask for or print the bearer token.
2. Create or select the book. For a new book, call POST /books with title and bookType.
3. Build planning material. Either draft it yourself from the user's brief or use POST /ai/generate-plot and POST /ai/generate-chapters.
4. Save structure with repeated PUT /books/{id}/structure calls for plot, characters, style, optional places_things, and chapters.
5. For each chapter:
   • Update agent state if the user wants progress visible in the portal.
   • Generate text with POST /ai/generate-text.
   • Review for user constraints, obvious factual issues, and continuity.
   • Save approved text with POST /books/{id}/content.
   • Summarize it with POST /consistency/chapter-summary.
6. After a complete drafting pass, call POST /consistency/update-story, fetch stats, and run consistency checks on risky sections.
7. Export with GET /books/{id}/download/{format} when the user asks for a deliverable. Supported formats are pdf, docx, epub, and html.

Command Contract

Run login and API requests through the gateway-proxied helper. Copy these commands exactly, changing only the operation arguments such as title, book id, or file paths:

node skills/hermes3000-writing/scripts/hermes3000.cjs --help

Capture the JWT into the secret store:

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run auth.login

This is an agent-side command. Do not show it to chat/TUI users as something they need to run.

Create a book:

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run books.create \
  --title "Working Title" \
  --book-type prose

Save a Markdown structure element:

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run structure.put \
  --book-id 42 \
  --structure-type plot \
  --content-file plot.md

Save chapters with UUIDs:

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run structure.put \
  --book-id 42 \
  --structure-type chapters \
  --content-json '[{"id":"550e8400-e29b-41d4-a716-446655440000","title":"Chapter 1","summary":"Opening movement."}]'

Generate and save chapter text:

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run ai.generate-text \
  --book-id 42 \
  --chapter-id "Chapter 1" \
  --prompt "Write the opening scene."

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run content.save \
  --book-id 42 \
  --chapter-uuid 550e8400-e29b-41d4-a716-446655440000 \
  --content-file chapter-1.html

Build consistency memory and export:

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run consistency.chapter-summary \
  --book-id 42 \
  --chapter-id "Chapter 1" \
  --chapter-uuid 550e8400-e29b-41d4-a716-446655440000 \
  --chapter-content-file chapter-1.html \
  --narrative-order 0 \
  --lang en

node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run consistency.update-story --book-id 42
node skills/hermes3000-writing/scripts/hermes3000.cjs --format json run export.download --book-id 42 --export-format docx

Writing Guidance

• For novels, make the chapter prompt scene-specific: point of view, location, time, objective, conflict, emotional turn, continuity constraints, and ending beat.
• For nonfiction and whitepapers, make the chapter prompt argument-specific: audience, claim, evidence to use, terms to define, examples, counterarguments, and desired takeaway.
• For long reads, prefer shorter content blocks per chapter section so revision remains manageable.
• Use POST /consistency/check when new text might contradict earlier claims, timeline, character state, terminology, or technical definitions.
• Keep generated HTML returned by Hermes3000 intact unless the target content block should be plain text.

Error Handling

• 401 means login failed or the token expired; re-authenticate through the secure credential path.
• 402 means account limits or payment requirements blocked book creation. Report it plainly; do not retry creation.
• 403 usually means unverified email, insufficient account level, or missing ownership. Fetch book metadata only if authorized.
• 404 means the book, structure, chapter, or content block is unavailable to the current user.
• If generation succeeds but saving fails, keep the generated text in the current response or workspace artifact only when it does not expose secrets or private source material, then ask before retrying.