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.

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

`DAYBOOK_TOKEN` is a personal per-user token, from Settings → Account in the app — not a token shared across users. Override these per environment.

## Commands

Check the instance:

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

Post Markdown from a file:

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

Post Markdown from stdin:

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

Post a deck:

```bash
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:

```bash
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):

```bash
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):

```bash
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):

```bash
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):

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```text
skills/daybook-posting/SKILL.md
```

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