fieldpacket

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:

1. 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.
2. 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.
3. 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.
4. Audit the raw research before synthesis: source count, source quality, contradictions, duplicate authoritative sources, and thin subtopics.
5. Synthesize the final markdown yourself into a decision-grade report. Do not concatenate subtopic notes.
6. Prefer high-quality current sources: manufacturer pages, primary docs and specs, professional reviews, retailers, credible forums where useful.
7. Include recommendations, comparison criteria, tradeoffs, who should buy or avoid, price/value notes, caveats, source links, and a clear final call.
8. Preserve auditable source links; flag uncertainty where sources disagree.
9. 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:

1. Read docs/visual-standard.md.
2. Read workflows/publish-report.js for the current build/polish brief.
3. Write a single self-contained HTML report to $FIELDPACKET_ROOT/reports/<slug>.html.
4. Write the sidecar JSON to $FIELDPACKET_ROOT/meta/<slug>.json with: slug, title, subtitle, date, tags, summary, sources, method.
5. Run the adversarial polish pass over the HTML yourself (mobile tables, content integrity vs the markdown, design fidelity, accessibility).
6. 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:

1. Check what exists: source markdown, HTML, sidecar, index entry.
2. If the markdown exists but HTML/meta are missing, re-run only the render/index/verify steps — do not redo the research.
3. 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          # http://127.0.0.1:8110
fieldpacket serve 9000     # custom port

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>        # default 900px width
fieldpacket pdf <slug> 1200   # wider render

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)