| name | fieldpacket |
| description | Use for the research-to-report workflow — researching a topic into a deep-dive report and publishing it as a Fieldpacket field packet. Covers publishing markdown to HTML via the publish-report workflow, library index rebuilds, report verification, rescuing partial publishes, serving the library, and report PDFs. |
Fieldpacket
Fieldpacket is the research-to-report workflow: research a topic properly,
then publish the result as a designed, self-contained field packet in the
user's library.
It is agent-driven — you do the research and you design each report's HTML
against the house standard. The CLI is the deterministic half — it builds
the library index, serves it, renders PDFs, and verifies the result. There are
no API keys; your coding-agent session is the engine.
System Map
- Toolkit checkout:
<fieldpacket-dir> (this repo, e.g. ~/repos/fieldpacket)
- Library root:
$FIELDPACKET_ROOT (default ~/fieldpacket)
- Source markdown:
$FIELDPACKET_ROOT/source/<slug>.md
- Published HTML:
$FIELDPACKET_ROOT/reports/<slug>.html
- Metadata sidecar:
$FIELDPACKET_ROOT/meta/<slug>.json
- Library index:
$FIELDPACKET_ROOT/index.html
- CLI:
<fieldpacket-dir>/bin/fieldpacket
- Index builder:
<fieldpacket-dir>/src/index.ts
- PDF renderer:
<fieldpacket-dir>/src/pdf.ts
- Publish workflow:
<fieldpacket-dir>/workflows/publish-report.js
- PDF workflow:
<fieldpacket-dir>/workflows/report-to-pdf.js
Read First
For publishing tasks, read only what you need:
- Visual quality bar:
<fieldpacket-dir>/docs/visual-standard.md
- Build/polish brief:
<fieldpacket-dir>/workflows/publish-report.js
- Research method: the
deep-dive skill
Research Workflow
For a new deep-dive or product report:
- Set the research tier:
- Focused: narrow comparison, 5-7 subtopics, 40-60 sources.
- Standard: normal report work, 7-9 subtopics, 60-80 sources.
- Comprehensive: broad landscape, 9-12 subtopics, 80-100+ sources.
- Decompose the topic into distinct angles before searching: current state,
major contenders, primary specs, price/value, reviews and complaints,
alternatives, limitations, buyer fit, and future direction where relevant.
- Run parallel research agents by subtopic. Each gathers 8-15 high-quality
sources, annotates what each source uniquely contributed, and calls out
contradictions or uncertainty.
- Audit the raw research before synthesis: source count, source quality,
contradictions, duplicate authoritative sources, and thin subtopics.
- Synthesize the final markdown yourself into a decision-grade report. Do not
concatenate subtopic notes.
- Prefer high-quality current sources: manufacturer pages, primary docs and
specs, professional reviews, retailers, credible forums where useful.
- Include recommendations, comparison criteria, tradeoffs, who should buy or
avoid, price/value notes, caveats, source links, and a clear final call.
- Preserve auditable source links; flag uncertainty where sources disagree.
- Avoid thin affiliate-listicle output.
The deep-dive skill carries the full method, including agent prompt templates
and per-tier word and source targets.
Publish Workflow
Preferred contract:
Workflow({
name: 'publish-report',
args: {
srcMd: '/absolute/path/to/report.md',
slug: 'report-slug',
title: 'Report title',
subtitle: 'Short subtitle',
tags: ['tag-one', 'tag-two'],
summary: 'One or two sentence summary',
root: '~/fieldpacket',
fieldpacketDir: '~/repos/fieldpacket'
}
})
If workflow invocation is unavailable, implement the same contract manually:
- Read
docs/visual-standard.md.
- Read
workflows/publish-report.js for the current build/polish brief.
- Write a single self-contained HTML report to
$FIELDPACKET_ROOT/reports/<slug>.html.
- Write the sidecar JSON to
$FIELDPACKET_ROOT/meta/<slug>.json with:
slug, title, subtitle, date, tags, summary, sources, method.
- Run the adversarial polish pass over the HTML yourself (mobile tables,
content integrity vs the markdown, design fidelity, accessibility).
- Rebuild and verify:
fieldpacket index
fieldpacket verify <slug>
Do not mark a report complete until the HTML exists, the sidecar is valid JSON,
the index is rebuilt, and fieldpacket verify <slug> prints ok on every line.
Visual Standard
Reports must match the house style, not a plain article.
- Warm "carpenter's field estimate / job ticket" look.
- Palette:
--ink #2B2118, --paper #ECE3D0, --surface #FBF8F1,
--barn #9E2B25, --pine #33453A, --brass #C8943B,
--brass-text #8A5A12.
- Fonts: Bricolage Grotesque (display), Newsreader (body), Space Mono (data).
- Topbar chips, perforated/stamped hero, stamp grid, metadata grid, numbered
TOC, section markers, at least two decision components, source/audit trail,
print CSS, reduced-motion handling, visible focus, mobile-safe tables.
- Serious reports generally exceed 20KB of HTML with 8+ distinct component
classes. Thin output is a failure even when the content is correct.
Full standard and rejection criteria: docs/visual-standard.md.
Rescue Workflow
For a stalled or partial publish:
- Check what exists: source markdown, HTML, sidecar, index entry.
- If the markdown exists but HTML/meta are missing, re-run only the
render/index/verify steps — do not redo the research.
- Preserve the original slug unless the user asks for a new version.
fieldpacket list
fieldpacket verify <slug>
ls -l "$FIELDPACKET_ROOT/reports/<slug>.html" "$FIELDPACKET_ROOT/meta/<slug>.json"
Serving
fieldpacket serve
fieldpacket serve 9000
The library is plain static files, so it can also be uploaded to any static
host. Publish index.html, reports/, and meta/; leave source/ and pdf/
out unless you intend them to be public.
PDF Export
fieldpacket pdf <slug>
fieldpacket pdf <slug> 1200
Renders via puppeteer-core plus a local Chrome/Chromium as a faithful single
continuous page, preserving on-screen styling and forcing scroll-reveal content
visible. Set FIELDPACKET_CHROME if Chrome is not auto-detected.
Completion Note
Report completion should include:
- The report path (and local URL if serving)
- The strongest recommendation or headline finding
- Files written or changed
- Source count
- Verification result (
fieldpacket verify <slug> all ok)
