diff --git a/skills/daybook-posting/SKILL.md b/skills/daybook-posting/SKILL.md index 51f4dc5..c972af9 100644 --- a/skills/daybook-posting/SKILL.md +++ b/skills/daybook-posting/SKILL.md @@ -1,26 +1,13 @@ --- name: daybook-posting -description: Use when you have produced a finished deliverable such as a report, summary, brief, diagram, generated HTML, PDF, deck, or status update that a human should review later outside this chat. Publishes the artifact to Daybook and returns a URL. +description: Use when you have produced a finished deliverable such as a report, summary, brief, diagram, generated HTML, PDF, deck, or status update that a human should review later outside this chat. Publishes the artifact to a Daybook instance and returns a URL. --- # Daybook Posting Daybook is a private artifact journal for completed agent outputs. It stores, indexes, and displays artifacts for human review. It does not execute commands, run workflows, or continue conversations. -Always use the helper script. Do not hand-build curl, JSON, PowerShell multipart, or inline shell content. - -From the project root: - -```bash -python skills/daybook-posting/scripts/daybook_post.py --check -python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report" --content-file report.md -cat report.md | python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report" -python skills/daybook-posting/scripts/daybook_post.py --file diagram.svg --title "Architecture Diagram" -``` - -The project also keeps a compatibility wrapper at `scripts/daybook_post.py`, but the canonical helper is bundled inside this skill. - -The artifact URL is printed as the final stdout line. +You post to a **running Daybook server**, which may be anywhere — a cloud VM, a container, or a workstation. You do **not** need a checkout of Daybook's source. The only things that tie you to a particular instance are two environment variables: `DAYBOOK_URL` (where the server is) and `DAYBOOK_TOKEN` (who you are). Set those and the rest of this skill works unchanged regardless of where you or the server run. ## Configuration @@ -30,12 +17,54 @@ config) — the helper reads `os.environ` directly. There is no `.env` file support; a `.env` file in the working directory is not read automatically. ```text -DAYBOOK_URL=http://127.0.0.1:8001 -DAYBOOK_TOKEN=your-personal-api-token -DAYBOOK_SOURCE=agent +DAYBOOK_URL=https://your-daybook-instance.example.com # your server's base URL +DAYBOOK_TOKEN=your-personal-api-token # from Settings -> Account +DAYBOOK_SOURCE=agent # a stable label for what's posting ``` -`DAYBOOK_TOKEN` is your personal per-user API token, from Settings → Account in the app (not a token shared by everyone). Artifacts posted with your token land only in your feed. +- **`DAYBOOK_URL`** — the base URL of the Daybook instance you're posting to. + Set it to your server. If it's unset, the helper falls back to + `http://127.0.0.1:8001`, which is only correct when Daybook is running + locally on the same machine (its development default). For any remote or + deployed instance you **must** set this. +- **`DAYBOOK_TOKEN`** — your personal per-user API token, from Settings → + Account in the app (not a token shared by everyone). Artifacts posted with + your token land only in your feed. +- **`DAYBOOK_SOURCE`** — a free-text label for whatever is posting + (agent-profile, script, or person name). Optional; can also be passed per + call with `--source`. + +## The Helper + +Always use the bundled helper script. Do not hand-build curl, JSON, +PowerShell multipart, or inline shell content (a `curl` fallback for +environments without the helper is documented at the end — the script is +still preferred everywhere it's available). + +The helper lives at **`scripts/daybook_post.py` inside this skill's own +directory** — not in any project you happen to be working in. Invoke it by +its absolute path. For brevity, the examples below assume you've captured +that path once: + +```bash +# Point this at the helper inside THIS skill directory (absolute path). +DAYBOOK_POST=/abs/path/to/this/skill/scripts/daybook_post.py +``` + +Then: + +```bash +python "$DAYBOOK_POST" --check +python "$DAYBOOK_POST" --kind markdown --title "Build Report" --content-file report.md +cat report.md | python "$DAYBOOK_POST" --kind markdown --title "Build Report" +python "$DAYBOOK_POST" --file diagram.svg --title "Architecture Diagram" +``` + +The artifact URL is printed as the final stdout line. + +(If you *are* working inside a Daybook source checkout, a compatibility +wrapper also exists at `scripts/daybook_post.py` in the repo root, but the +canonical helper is the one bundled in this skill.) ## Kind Cheat Sheet @@ -65,8 +94,9 @@ presentation. This script only **creates** artifacts — none of the following are possible through it. Updating an existing artifact's title/tags/metadata, -or deleting one, requires the raw API (see `docs/api.md`); enabling its -public share link is feed-UI-only, with no API equivalent at all yet. +or deleting one, requires the raw API (see the instance's `docs/api.md` or +`GET /api/capabilities`); enabling its public share link is feed-UI-only, +with no API equivalent at all yet. ## CDN Snippets For `html_full` @@ -119,11 +149,12 @@ artifact), upload it first and reference the returned URL: ```bash # 1. Upload -> prints the URL as the last line -python skills/daybook-posting/scripts/daybook_post.py --upload-image chart.png +python "$DAYBOOK_POST" --upload-image chart.png -# 2. Reference that URL in your markdown, then post as usual -# ![chart](http://127.0.0.1:8001/assets/ab12cd34ef56) -python skills/daybook-posting/scripts/daybook_post.py report.md +# 2. Reference that URL in your markdown, then post as usual. +# The printed URL is absolute against your DAYBOOK_URL, e.g. +# ![chart]($DAYBOOK_URL/assets/ab12cd34ef56) +python "$DAYBOOK_POST" report.md ``` The image is linked to the artifact that references it and is deleted along with it. @@ -136,19 +167,19 @@ just post the file positionally; auto-mode detects `.csv`/`.json` and picks the right kind automatically: ```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 +python "$DAYBOOK_POST" results.csv +python "$DAYBOOK_POST" --kind json --title "Run Summary" --content-file summary.json ``` `.xlsx` spreadsheets work too, with no special flag needed — just `--file` (or post it positionally, same as any other file): ```bash -python skills/daybook-posting/scripts/daybook_post.py balance_sheet.xlsx +python "$DAYBOOK_POST" balance_sheet.xlsx ``` The server converts it to a `csv` artifact automatically. Known -limitations (see `docs/api.md` for the full list): +limitations (see the instance's `docs/api.md` for the full list): - Only the workbook's **active sheet** converts; other sheets are dropped. - Formula cells need to have been calculated and saved by real spreadsheet @@ -165,7 +196,7 @@ as a binary, use `--file path --as-markdown` to wrap it in a Markdown fenced code block (still gets syntax highlighting): ```bash -python skills/daybook-posting/scripts/daybook_post.py --file script.py --as-markdown --title "Generated Script" +python "$DAYBOOK_POST" --file script.py --as-markdown --title "Generated Script" ``` Without `--as-markdown`, it uploads as a downloadable binary file instead. @@ -189,8 +220,37 @@ context like `run_id` or `model` — these end up in the artifact's ## Rules - Run `--check` first if unsure Daybook is reachable. +- Make sure `DAYBOOK_URL` points at the right instance and `DAYBOOK_TOKEN` is set before posting anything real. - Use a stable `DAYBOOK_SOURCE` or pass `--source` (the agent-profile, script, or person name that produced this artifact). - Use `--tags a,b,c` for filtering. - Use `--meta run_id=... --meta model=...` for machine-readable context. - Never inline multiline content into the shell command; use a file or stdin. - Add `--dry-run` to see exactly what would be sent (method, headers, payload) without actually posting — useful when unsure a payload is well-formed. + +## `curl` Fallback (No Helper Available) + +Prefer the helper above — it handles multipart, content-type inference, +JSON shaping, and provenance flags for you. Use raw `curl` **only** when you +genuinely can't run the bundled Python script (e.g. a minimal environment +with no Python). Text artifacts post as JSON to `POST /api/artifacts` with +bearer-token auth: + +```bash +curl -sS -X POST "$DAYBOOK_URL/api/artifacts" \ + -H "Authorization: Bearer $DAYBOOK_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"kind":"markdown","title":"Build Report","source":"agent","content":"# Hello\n\nBody text."}' +``` + +File/image artifacts use multipart instead: + +```bash +curl -sS -X POST "$DAYBOOK_URL/api/artifacts" \ + -H "Authorization: Bearer $DAYBOOK_TOKEN" \ + -F "kind=image" -F "title=Architecture Diagram" -F "source=agent" \ + -F "file=@diagram.png" +``` + +`GET $DAYBOOK_URL/api/capabilities` (no auth needed beyond a login/token per +that instance's config) lists supported kinds, methods, and the server +version if you need to confirm the contract before posting.