# Hardware Pattern Telemetry

> Anonymized community-shared hardware patterns. Generated from opt-in learnings.
> See CONTRIBUTING.md for how to opt-in / opt-out / inspect before share.

_Generated: 2026-04-19T12:58:16.592Z_

_No public hardware-pattern learnings to report._

---

## How to contribute hardware patterns

Hardware-pattern learnings are generated by `/evolve analyze` and stored in
`.orchestrator/metrics/learnings.jsonl` with `scope: private` by default.
The rendered table above only reflects entries with `scope: public` — so it
will be empty until you run the promotion step.

### Promotion workflow

1. **Generate learnings** — run `/evolve analyze` at least once so
   `learnings.jsonl` contains `hardware-pattern` entries.

2. **Inspect private entries** — check `.orchestrator/metrics/learnings.jsonl`
   for entries with `"type":"hardware-pattern","scope":"private"`. These contain
   only structured fields (no free-form text) and are never exported without
   your action.

3. **Promote private → public** — run the promotion pipeline:

   ```bash
   npm run share:hw-learnings -- --promote
   ```

   This will:
   - Anonymize every `scope: private` hardware-pattern entry (paths, IPs,
     emails, VCS URLs, tokens all redacted; RAM/CPU bucketed).
   - Stamp each promoted copy with `anonymized: true` and
     `anonymization_version`.
   - Validate each promoted entry through the privacy contract
     (`validateLearning`) — a violation is a fatal error; no partial write.
   - Back up `learnings.jsonl` to `learnings.jsonl.bak-<ISO>` before rewriting.
   - Write the original private entries **plus** new public twin entries back to
     `learnings.jsonl`. The originals are preserved for host-local reference.
   - Re-render this file with the newly public entries.

4. **Preview without writing** (dry run):

   ```bash
   npm run share:hw-learnings -- --promote --dry-run
   ```

   Prints the promotion summary and rendered markdown to stdout; no files are
   mutated.

5. **Render only** (no promotion):

   ```bash
   npm run share:hw-learnings
   ```

   Re-renders this file from already-public entries. Use this if you already
   promoted and just want to refresh the doc.

### Privacy contract

- `scope: local` — never exported. May contain absolute paths, host info.
- `scope: private` — in-repo only. No host-identifying info required.
- `scope: public` — export-safe. Requires `anonymized: true` AND `host_class`
  set. The promotion pipeline enforces this via `validateLearning`.

### Rolling back

If you promoted by mistake, restore the backup:

```bash
cp .orchestrator/metrics/learnings.jsonl.bak-<ISO> .orchestrator/metrics/learnings.jsonl
```
