daybook/docs/llm_posting_helper.md

LLM Posting Helper

Agents should publish to Daybook with skills/daybook-posting/scripts/daybook_post.py instead of hand-building HTTP, JSON, curl, or PowerShell multipart requests.

The project also keeps scripts/daybook_post.py as a compatibility wrapper.

The helper is intentionally zero-dependency and uses only Python's standard library. It works on Windows and Linux.

It only creates artifacts. Updating (title/tags/metadata) and deleting require the raw API (PATCH/DELETE /api/artifacts/{id}, see docs/api.md); enabling a public share link is done from the feed UI and has no API or CLI path yet.

Configuration

Set these as real process/shell environment variables — the helper reads os.environ directly and has no .env file support. Copying values into a .env file in the working directory does nothing; export/$env:/set them, or set them in your agent harness's own env config.

DAYBOOK_URL=http://127.0.0.1:8001
DAYBOOK_TOKEN=your-personal-api-token
DAYBOOK_SOURCE=agent

DAYBOOK_TOKEN is a personal API key, created under Settings → API Keys in the app (one per agent, individually revocable) — not a key shared across users. Override these per environment.

Commands

Check the instance:

python skills/daybook-posting/scripts/daybook_post.py --check

Post Markdown from a file:

python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report" --content-file report.md --tags build,report

Post Markdown from stdin:

cat report.md | python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report"

Post a deck:

python skills/daybook-posting/scripts/daybook_post.py --kind deck --title "Deployment Plan" --content-file deck.html

deck.html must contain top-level <section>...</section> blocks.

Post an image/PDF/binary file:

python skills/daybook-posting/scripts/daybook_post.py --file diagram.svg --title "Architecture Diagram"
python skills/daybook-posting/scripts/daybook_post.py --file report.pdf --title "Generated Report"

Post CSV or JSON as an interactive table/tree (auto-mode detects the kind from the extension; explicit --kind works too):

python skills/daybook-posting/scripts/daybook_post.py results.csv
python skills/daybook-posting/scripts/daybook_post.py --kind json --title "Run Summary" --content-file summary.json

Post an .xlsx spreadsheet (converted server-side to a csv artifact — active sheet only, saved formula results only, no formatting preserved):

python skills/daybook-posting/scripts/daybook_post.py balance_sheet.xlsx

Render other code as a Markdown fenced block instead (no dedicated code kind yet):

python skills/daybook-posting/scripts/daybook_post.py --file script.py --as-markdown --title "Generated Script"

Embed an image inside a markdown/HTML artifact (upload first, then reference the printed URL in your content):

python skills/daybook-posting/scripts/daybook_post.py --upload-image chart.png
# -> prints .../assets/<id>; put that in your markdown, then post normally

Dry run:

python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Draft" --content-file report.md --dry-run

The artifact URL is printed as the final stdout line.

Validation Guardrails

The helper validates common LLM mistakes before sending:

Kind/input	Validation
deck	Must contain <section.
html_fragment	Must not contain <!doctype, <html, or <body.
html_full	Must contain <html (a <!doctype is recommended, not required).
markdown	Must not be blank.
json	Must be valid JSON (json.loads must succeed).
.svg upload	Forces image/svg+xml.
.pdf upload	Forces application/pdf.

Metadata

Use repeatable --meta key=value flags:

python skills/daybook-posting/scripts/daybook_post.py \
  --kind markdown \
  --title "Run Summary" \
  --content-file summary.md \
  --meta run_id=run-001 \
  --meta model=gpt-5.5

Or pass a JSON object:

python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Run Summary" --content-file summary.md --meta-json '{"run_id":"run-001"}'

--meta and --meta-json are merged if both are given. Metadata lives in the artifact's metadata field, separate from --tags (which are for filtering).

Source & Theme Flags

Flag	Default	Notes
--source	DAYBOOK_SOURCE env, else agent	What produced this — an agent-profile, script, or person name.
--source-type	agent	One of agent, person, system.
--source-name	The effective --source	Human-readable name, e.g. "Hermes Agent".
--source-id	Empty	A stable external ID, if one exists.
--source-prompt	Empty	The prompt/instruction behind the artifact.
--theme	Kind default	markdown/html_fragment only: report (default), tasks, or base. Other kinds ignore it.

Skill Wrapper

A thin LLM-facing wrapper lives at:

skills/daybook-posting/SKILL.md

Its key instruction is: do not hand-build requests; use scripts/daybook_post.py.