first-output-tour.md

Recoleta First Output Tour

Use this guide after your first run now. It tells you where to look after the default workflow and how to rerender one surface if you need to.

1. Check that the first run worked

If you ran:

uv run recoleta run now

or:

docker compose run --rm recoleta run now

open these paths first:

• MARKDOWN_OUTPUT_DIR/latest.md or ./data/outputs/latest.md: summary page for the latest publish run. This file is a publish index, not a global freshness summary for data, workflow windows, or backups.
• MARKDOWN_OUTPUT_DIR/Inbox/: one Markdown note per published item
• MARKDOWN_OUTPUT_DIR/Trends/: day-level trend notes from the same workflow, plus adjacent .presentation.json sidecars for canonical trend notes
• MARKDOWN_OUTPUT_DIR/site/index.html: the rebuilt static site
• RECOLETA_DB_PATH: the SQLite database that later workflows build from
• MARKDOWN_OUTPUT_DIR/Ideas/ when the day has enough evidence, plus adjacent .presentation.json sidecars for canonical idea notes
• MARKDOWN_OUTPUT_DIR/Localized/<language>/ when localization.targets is configured. Localized trend and idea notes also emit adjacent .presentation.json sidecars; localized item notes remain markdown-only.

If you started from a preset, use the output paths in that preset YAML file.

If dates disagree across these surfaces, check freshness explicitly:

uv run recoleta inspect freshness

inspect freshness separates run freshness, item-data coverage, derived trend or idea windows, and the latest DB backup recovery point. Use it instead of guessing from latest.md or one recent run row.

2. Rerender one surface only

A normal run now already attempts publish, day-level trends, day-level ideas, and site build. It also attempts translation when localization.targets is configured. Use these commands only when you want to rerender one surface:

uv run recoleta stage trends --granularity day --date 2026-03-14
uv run recoleta stage ideas --granularity day --date 2026-03-14
uv run recoleta run site build

That updates:

• MARKDOWN_OUTPUT_DIR/Trends/
• MARKDOWN_OUTPUT_DIR/Ideas/ when the selected day has enough evidence
• MARKDOWN_OUTPUT_DIR/site/index.html and the related trend or idea pages

For canonical trend and idea notes, the same rerender also refreshes the adjacent .presentation.json sidecars in those directories. If localization is configured, recoleta run translate materializes localized trend and idea sidecars beside the localized markdown notes.

stage ideas needs an existing trend synthesis output for the same window. Low-evidence windows can still be suppressed.

3. Compare your output with the public examples

Site home

Local path:

• MARKDOWN_OUTPUT_DIR/site/index.html

Public example:

• https://neapolitanicecream.github.io/recoleta/

Trend note

If run now already created a day brief, open it. To rerender a specific day:

uv run recoleta stage trends --granularity day --date 2026-03-14

Local paths:

• MARKDOWN_OUTPUT_DIR/Trends/*.md
• MARKDOWN_OUTPUT_DIR/Trends/*.presentation.json
• MARKDOWN_OUTPUT_DIR/site/trends/*.html

Public examples:

• https://neapolitanicecream.github.io/recoleta/en/trends/index.html
• https://neapolitanicecream.github.io/recoleta/en/streams/software-intelligence.html

Idea note

If the workflow created ideas for that day, open them. To rerender a specific day:

uv run recoleta stage ideas --granularity day --date 2026-03-14

Local paths:

• MARKDOWN_OUTPUT_DIR/Ideas/*.md
• MARKDOWN_OUTPUT_DIR/Ideas/*.presentation.json
• MARKDOWN_OUTPUT_DIR/site/ideas/*.html

Public examples:

• https://neapolitanicecream.github.io/recoleta/en/ideas/index.html
• https://neapolitanicecream.github.io/recoleta/en/streams/software-intelligence.html

4. Pick the closest preset example

Agents radar

• Start from: presets/agents-radar.yaml
• Closest public example: https://neapolitanicecream.github.io/recoleta/en/streams/software-intelligence.html
• Expect: latest.md, Inbox/, trend notes, idea notes when evidence is strong enough, and the static site. Here latest.md is still only the latest publish index.

Robotics radar

• Start from: presets/robotics-radar.yaml
• Closest public example: https://neapolitanicecream.github.io/recoleta/en/streams/embodied-ai.html
• Expect the same output structure, but with robotics-heavy source material

arXiv digest

• Start from: presets/arxiv-digest.yaml
• Closest public example: https://neapolitanicecream.github.io/recoleta/en/trends/index.html
• Expect the same output structure, but from a paper-only corpus