# Tokenstopia Trace Publishing Pack

This workflow prepares a **small, safe first publication** for Hugging Face Agent Trace Viewer audiences.

Scope:
- no new MCP tools
- no website redesign
- no auto-upload

## First publication audit (decision)

Current available traces: 5
- `01-infer-identity-basic`
- `02-simulate-disagreement`
- `03-estimate-compatibility`
- `04-chain-profile-to-duel`
- `05-invalid-input`

First public release includes **4 traces**:
1. `01-infer-identity-basic` (start here)
2. `02-simulate-disagreement`
3. `03-estimate-compatibility`
4. `05-invalid-input` (advanced/optional)

Deferred from first release:
- `04-chain-profile-to-duel` (kept for second wave to reduce first-viewer cognitive load)

Reason: first publication should be concise and easy to parse for external reviewers.

## Real vs representative

- Included traces are `real_sanitized_trace` (captured from real stdio MCP calls, then sanitized).
- No representative/seeded traces in this first publication release.

## Folder structure

```text
trace-pack/
  source/
    raw/                                     # local artifacts, never publish
  export/
    hf-agent-trace-viewer/                   # full sanitized export (5 traces)
  release/
    first-publication/                       # curated first public subset (4 traces)
      README.md
      REDACTION_SUMMARY.md
      manifest.json
      traces.jsonl
      traces/
        *.json
  hf-publication.json                        # pending/live URL status update point
```

## Scripts

- Build full raw traces: `npm run trace:build`
- Build one reproducible sample trace (infer tool): `npm run trace:sample-infer`
- Sanitize full export: `npm run trace:sanitize`
- Verify full export: `npm run trace:verify`
- Curate first public subset: `npm run trace:release`
- Verify first publication package: `npm run trace:verify-publication`
- One-pass first-publication prep: `npm run trace:first-publication`

## Redaction policy

Never publish raw traces.

Sanitization masks/removes:
- secret-like keys (`token`, `authorization`, `apiKey`, `secret`, `password`, `cookie`)
- token-like string patterns (bearer/prefixed secrets)
- personal email patterns
- local user path patterns

Primary files:
- `scripts/sanitize-traces.js`
- `trace-pack/export/hf-agent-trace-viewer/sanitization-report.json`
- `trace-pack/release/first-publication/REDACTION_SUMMARY.md`

## Upload flow (human-reviewed)

1. `npm run trace:first-publication`
2. Review `trace-pack/release/first-publication/README.md`
3. Review `manifest.json` and `REDACTION_SUMMARY.md`
4. Review export verification reports:
   - `trace-pack/export/hf-agent-trace-viewer/verification-report.json`
   - `trace-pack/export/hf-agent-trace-viewer/verification-report.md`
5. Spot-check trace files
6. Upload `trace-pack/release/first-publication/` contents to HF dataset
7. Update `trace-pack/hf-publication.json` with live dataset URL
8. Verify `trace-gallery.html` reflects live status

## First-time developer understanding path

If this is your first time reviewing Tokenstopia traces:

1. Open `trace-pack/export/hf-agent-trace-viewer/manifest.json`.
2. Pick trace `01-infer-identity-basic` and inspect one request/response event.
3. Confirm `tools_called`, `request_fields`, `response_fields`, and `sanitization` metadata.
4. Open `verification-report.md` to see whether the pack is currently review-ready.

## Known limitations

- secret scan is heuristic, not exhaustive
- no auto-upload by design
- first release intentionally excludes one multi-step chain trace