The catalog

# Add your devices

Discover what is present, then choose all uncatalogued devices, all devices for review, or just the ones you select. No device settings are changed.

## The quick way: paste this into your coding agent

Use any coding agent with terminal and file access. It discovers the current devices, checks the registry, asks which entries to work on, and writes or reviews their cards with you. Nothing is published without your choice.

```
Help me add or review the devices I choose in Hardpoint: https://github.com/dotCipher/hardpoint

Work with me one step at a time. The registry is the only source for device
cards, abilities, labels, adapter status, platforms and helper requirements.
Do not assume a fixed device list or infer coverage from documentation examples.

1. Find an existing checkout or clone the repository without overwriting anything. Read AGENTS.md, docs/SPEC.md, the card schema, and the current registry under catalog/. Check personal cards under the configured Hardpoint cards directory too; do not copy private cards into a public contribution without my review.
2. Explain the read-only discovery scope and offer local-only discovery with `--no-network` if I do not want network discovery. Inspect the script's current `--help` rather than inventing options. Save one `python3 tools/observe.py --json` result in a private temporary snapshot outside the repository, adding `--no-network` if selected. Do not publish that snapshot.
3. Show a numbered inventory from that snapshot, including entries with an existing shared or personal card. Mark what needs a new card versus review. Ask me to choose before writing any cards:
   - All uncatalogued devices (`missing`).
   - All detected devices for review (`all`); reuse existing cards and draft only missing ones.
   - Specific snapshot numbers or ranges, such as `1,3-5`. If I give names, resolve them against this inventory and ask about ambiguous matches.
   Let me exclude entries from either all-device option. An empty inventory or selection is a valid stop, not a reason to guess devices.
4. Confirm the selected entries and proposed create/reuse/review actions. Use `python3 tools/observe.py --from-file <private-snapshot-path> --select <selection> --json` to preserve the original numbering. Keep the original unfiltered snapshot as the source, not a filtered selection export. Do not rescan and silently apply my old numbers to a reordered inventory. If discovery changes, ask me to confirm a new selection. Discovery can group identical models: work only on selected entries and do not create duplicate model cards for multiple units/observations or copies of an existing card.
5. Research each selected public model using the maker's product/support or identification pages, and record those sources on its card. Do not infer a retail model, generation, capacity or enclosure from a generic announcement or a friendly name I gave the device. Use a family identity when the exact model is not established, and class identity for integration entity classes. Normalize reviewed names with `python3 tools/observe.py --normalize --vendor "<public maker>" --name "<public model name>" --kind "<category or alias>" --identity "<registry identity scope>"`. It reads maker aliases/categories from catalog/vocabulary/devices.json, reports existing cards and writes nothing. Register a new maker there with my review when needed; never silently rename an existing card id. For a reviewed correction, pass `--card-id "<existing id>"` to preserve it.
   A shared display name is not proof of the same physical model. Use `--model-code "<reviewed public model code>"` to disambiguate same-named variants, and compare the matching evidence. Never use a serial number as that code. For a selected uncatalogued entry, use `python3 tools/observe.py --from-file <private-snapshot-path> --draft <original-number>` and optionally pass those reviewed identity arguments to produce normalized fields. Without them it deliberately leaves TODO names, not a guessed identity. Confirm the destination and do not overwrite an existing shared or personal file. For an existing card, show the exact proposed diff instead of replacing it.
6. Fill in only what the current registry and evidence justify. Choose ability ids, label floors, adapter routes and typed parameters from catalog/ and the actual adapter implementation. Reuse an existing route where it fits; a missing adapter is a blocker, not permission to invent support or install another controller. Propose a genuinely missing vocabulary entry separately and ask me first. Never put commands, scripts, paths, serial numbers, addresses, host names or private device names into a shared card.
7. Verify selected entries read-only. If Hardpoint is installed, ask before placing reviewed cards in my personal cards directory, preserve existing contents, then reload and read only those selected abilities. Explain that reload may trigger trusted helper setup according to my settings. Do not restart or rebuild the daemon, elevate privileges, grant permissions, install unrelated software, flash firmware or change a device setting to make a test pass. Report disconnected, permission-blocked, ambiguous or unsupported results without claiming success.
8. Record only the operation actually exercised: `tested` for a successful read through its real adapter; `observed` for a separate direct observation; `unverified` for documentation alone. Use the actual observation date, platform and versions, and state explicitly when writes/undo were not tested. Do not turn one successful read into a tested whole card. Work from observation and primary documentation, not copied third-party data files; list sources.
9. Run `python3 tools/build.py --check` and relevant tests. Show a per-selected-entry summary: created, reused, changed, skipped or blocked, with evidence and exact files. Do not write a second device/support inventory into README, AGENTS.md or other docs.
10. Ask whether I want local-only use or a public contribution. Only after I approve the sanitized diff and publication should you prepare a pull request containing the selected changes. Exclude private snapshots, raw inventory, local routes, configs and logs. Leave unselected devices and unrelated work alone.
```

## Or by hand

Get the files

```
git clone https://github.com/dotCipher/hardpoint && cd hardpoint
```

See what is plugged in or on your home network, and what has no card yet

```
python3 tools/observe.py
```

Capture a private discovery snapshot, then select all missing cards or specific snapshot numbers

```
python3 tools/observe.py --json > <private-snapshot-path>
python3 tools/observe.py --from-file <private-snapshot-path> --select missing --json
python3 tools/observe.py --from-file <private-snapshot-path> --select 1,3-5 --json
```

Fill it in, then check it

```
python3 tools/build.py --check
```

Send it in as a pull request

## What makes a good card

- Only say `observed` for something you ran and saw work. Otherwise say `unverified`, and where the claim comes from.
- Use words from the shared list. If one is missing, add it in the same change.
- A card is information only. It can never contain a command.
- Write from what you see and from documentation. Do not copy another project's data files.

## Short on time?

Tell us what you have and paste what the script printed. Someone else can write the card.

[Open a device request](https://github.com/dotCipher/hardpoint/issues/new?template=device.yml)
