From c9edac62cf627022d5c23ce3ec6cf9ecb7d3e10c Mon Sep 17 00:00:00 2001 From: peter Date: Wed, 2 Sep 2026 16:49:19 +0100 Subject: [PATCH] Review docs/api.md and docs/llm_posting_helper.md for accuracy and completeness Same pass as the SKILL.md review. Fixed factually-wrong content and filled gaps against the current code. docs/api.md: - Capabilities example response was stale: artifact_kinds missing json/csv, raw_supported_for missing json/csv. Corrected to match live output, with a note that the endpoint is the authoritative source. - "Office document conversion is not implemented" is now false - replaced with the accurate scope (.xlsx -> csv only; .docx/.pptx/.xls not). - Source Fields overview table omitted source_prompt entirely; added it, plus a note that source_name/source_id/source_prompt must be strings (400, not coerced) and metadata must be an object. - Kinds table: noted tables now render styled in markdown/html_fragment, and made explicit that html_full is served verbatim with no styling. - MVP constraints: noted the public-share-link exception to "feeds private per user" and clarified PATCH edits metadata only. docs/llm_posting_helper.md: - Added .xlsx upload, --upload-image image embedding, a Source & Theme Flags table (all six source-*/theme flags were undocumented here), and a note that --meta/--meta-json merge and are distinct from tags. - Added a scope note that the helper only creates - update/delete need the API, sharing is feed-UI-only. Co-Authored-By: Claude Sonnet 5 --- docs/api.md | 27 +++++++++++++++++++-------- docs/llm_posting_helper.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 8 deletions(-) diff --git a/docs/api.md b/docs/api.md index e0b0036..362300e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -28,9 +28,9 @@ Currently supported kinds: | Kind | Upload type | Rendered behavior | Raw support | |---|---|---|---| -| `html_fragment` | JSON text | Wrapped with a Daybook theme | No | -| `html_full` | JSON text | Stored as complete HTML | Yes | -| `markdown` | JSON text | Rendered to HTML (fenced code blocks get syntax highlighting) and original `.md` is preserved | Yes | +| `html_fragment` | JSON text | Wrapped with a Daybook theme; tables styled automatically | No | +| `html_full` | JSON text | Stored as complete HTML, verbatim — no theme or styling injected | Yes | +| `markdown` | JSON text | Rendered to HTML (code blocks syntax-highlighted, tables styled) and original `.md` preserved | Yes | | `deck` | JSON text | Wrapped as a simple HTML slide/deck page | No | | `image` | Multipart file | Browser image preview | No | | `pdf` | Multipart file | Browser PDF preview | No | @@ -57,8 +57,13 @@ as coloured chips next to the title. The API exposes both separately, plus a com | `source_type` | No | `agent` | One of `agent`, `person`, `system`. | | `source_name` | No | `source` | Human-readable source name. | | `source_id` | No | Empty string | Stable external agent/person/system ID. | +| `source_prompt` | No | Empty string | The prompt/instruction that produced the artifact. | | `metadata` | No | `{}` | Free-form object for model/run/tool metadata. | +`source_name`, `source_id`, and `source_prompt` must be strings if provided +— sending an object, array, or number returns `400` (they are not coerced). +`metadata` must be an object. See "Create Text Artifact" for length limits. + Example source metadata: ```json @@ -498,10 +503,10 @@ Example response: ```json { - "artifact_kinds": ["html_fragment", "html_full", "markdown", "deck", "image", "pdf", "binary"], + "artifact_kinds": ["html_fragment", "html_full", "markdown", "deck", "image", "pdf", "binary", "json", "csv"], "filters": ["source", "label", "day", "kind", "q"], "views": ["rendered", "raw"], - "raw_supported_for": ["markdown", "html_full"], + "raw_supported_for": ["markdown", "html_full", "json", "csv"], "source_types": ["agent", "person", "system"], "auth": "bearer_token", "methods": { @@ -512,6 +517,9 @@ Example response: } ``` +This is generated from the server's actual configuration, so it's the +authoritative source if this document and a running instance ever disagree. + Agents should call this endpoint if they need to adapt to the current Daybook instance, or simply to check the instance is reachable and their token is valid. Unlike the other read endpoints, it accepts a bearer token as well as a browser session: @@ -523,8 +531,11 @@ curl -H "Authorization: Bearer " http://127.0.0.1:8001/api/ ## Current MVP Constraints - Each user has a personal ingest API token; there is no shared token. -- Reader/browser access requires login; feeds are private per user. -- Content modification/revisions are deferred. -- Office document conversion is not implemented. +- Reader/browser access requires login; feeds are private per user (except + per-artifact public share links — see Sharing above). +- Content modification/revisions are deferred (`PATCH` edits metadata only, + never `content`). +- Spreadsheet conversion covers `.xlsx` → `csv` only; other Office formats + (`.docx`, `.pptx`, legacy `.xls`) are not converted. - Manual browser upload/drag-and-drop is deferred. - Pagination/cursors are not implemented yet. diff --git a/docs/llm_posting_helper.md b/docs/llm_posting_helper.md index 9794324..6cafeb6 100644 --- a/docs/llm_posting_helper.md +++ b/docs/llm_posting_helper.md @@ -6,6 +6,11 @@ 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 @@ -64,6 +69,13 @@ 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): @@ -71,6 +83,14 @@ 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): + +```bash +python skills/daybook-posting/scripts/daybook_post.py --upload-image chart.png +# -> prints .../assets/; put that in your markdown, then post normally +``` + Dry run: ```bash @@ -112,6 +132,21 @@ 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: