Manual asset entry — log non-agent, non-discovered assets (printers, phones, spare equipment) into the unified device list

[ToddHebebrand]

Problem

The unified Devices list (#1424 / #1322) unions agent endpoints with discovered_assets, but every discovered_assets row requires a network footprint: ip_address is NOT NULL and part of the (org_id, ip_address) unique index (apps/api/src/db/schema/discovery.ts:132,170), and the only inserts come from network scans and UniFi sync (discoveryWorker.ts:983, unifiSyncService.ts, unifiTelemetryService.ts).

There is no way to log an asset with neither an agent nor a network presence: a spare laptop, a desk phone, a non-networked printer, loaned equipment. MSPs need one view of everything they are responsible for at a customer.

topologyManualNodes (discovery.ts:318-331) is a topology-diagram annotation, not an inventory record, and is never unioned into the list.

Current state

• apps/web/src/components/devices/DevicesPage.tsx:371-414,539 merges agent devices + network devices client-side behind ENABLE_NETWORK_DEVICES_IN_LIST.
• apps/api/src/routes/devices/network.ts:18-49 returns only approval_status='approved' AND linked_device_id IS NULL rows.
• No manual-asset route or table exists.

Proposed behavior

• "Add asset manually" from the Devices list, org- and site-scoped: name, asset type (reuse discovered_asset_type enum), manufacturer/model, serial, location/site, notes, optional assigned user.
• Either a source='manual' discriminator on a relaxed discovered_assets (nullable ip_address for manual rows) or a lightweight manual_assets table unioned as a third arm. Spec decides based on reuse of the detail-page/approval machinery.
• Manual assets are first-class in the list (sort/filter/paginate per Unified device list — per-asset detail pages and inline approval #1424) and eligible for warranty sync (manufacturer + serial feed warrantySync.ts) and for license/subscription tracking once that exists.

Acceptance criteria

• Create a manual asset from the Devices UI without scan or agent.
• Appears in the unified list, RLS-scoped, edit/delete supported.
• Manufacturer + serial make it eligible for the existing warranty lookup.
• Included in the device_inventory report type.
• RLS + cascade + export-policy registration if a new table is introduced.

Related

#1424, #1322, #3210, #3451.

---

Tracking issue for Manual asset entry — log non-agent, non-discovered assets (printers, phones, spare equipment) into the unified device list (manual-asset-entry).

• Plan: docs/superpowers/plans/device-lifecycle/2026-09-07-manual-asset-entry.md
• Spec: docs/superpowers/specs/device-lifecycle/2026-09-07-manual-asset-entry-spec.md

Waves are tracked as sub-issues. Managed by feature-lifecycle-mcp.

[ToddHebebrand]

Spec drafted

docs/superpowers/specs/device-lifecycle/2026-09-07-manual-asset-entry-spec.md on branch spec/4622-manual-asset-entry (commit 1076837). Docs only.

Shape: a new org-scoped manual_assets table (RLS Shape 1, breeze_has_org_access(org_id)), unioned into the Devices list as a third deviceClass: 'manual' arm beside agent and network. Reuses the discovered_asset_type enum and devices:read/write/delete; no new permission. No jsonb column anywhere, so nothing lands in the excludedOpen export bucket.

Two findings that bind the design either way. discovered_assets has no serial column, and warrantySync is hard-bound to a devices row (device_warranty.device_id NOT NULL + unique FK, warranty.ts:28-52) — so "manufacturer + serial feeds the existing warranty lookup" needs a subject-generalisation of the warranty subsystem under every option, which removes most of the reuse argument for relaxing discovered_assets. Separately, custom fields are device-only (composite FK (device_id, org_id) + a projection trigger), so they are deferred with a reason rather than assumed.

⚠️ The advisor quorum did not agree. Fable recommends a new table (B); Codex xhigh recommends a generic assets supertype (C), arguing that inventory identity should survive an asset gaining an agent. Both arguments are in the spec; this fork needs your call before a plan is written.

Open Decisions

1. Table shape — relax discovered_assets (A) / new manual_assets (B) / assets supertype (C)? A pollutes an observation table (auto-linker, disappeared-asset alerting, baseline detection, the pending queue all need source <> 'manual' guards no test enforces). C is the right end-state but adds asset_id to two shipped hot tables and re-keys warranty + custom fields. Recommend B — C's identity argument is strong, but adopting it means re-scoping Manual asset entry — log non-agent, non-discovered assets (printers, phones, spare equipment) into the unified device list #4622 from effort:m to a multi-wave feature specced with Unified device list — per-asset detail pages and inline approval #1424; B is a forward step toward C, not a detour.
2. Billable against device-set contract lines? Today billableDeviceConds is agent-devices-only. Recommend no — Breeze bills what it manages, and a typo'd inventory row must never raise an invoice. (Codex agrees.)
3. site_id required or optional? Recommend required — both existing classes are site-NOT-NULL and site-scoped tech permissions are enforced through it; nullable is a silent visibility hole. (Codex wants optional + an "Unassigned" facet.)
4. Custom fields in v1? Recommend no (notes + tags only) — the value table is device-coupled by composite FK and trigger; a jsonb bag is disqualified because it would vanish from tenant export. (Codex wants yes.)
5. Convert a manual asset into an agent device? Recommend link-only via linked_device_id, reversible, mirroring the shipped discovered-asset link; a destructive convert has no undo and discards exactly the fields agents cannot collect. (Codex agrees — and warns the MAC/IP auto-linker must never become a merge engine.)
6. CSV import in v1? Recommend no — preview, per-row errors and idempotency make it a second feature; the source enum ships with 'import' so it is additive. (Codex wants yes.)
7. Assigned person — users or org contact? Recommend contacts with a same-org composite FK; the holder of a customer's spare laptop is rarely a Breeze user. (Codex agrees.)

[ToddHebebrand]

Decision 1 resolved: option B (new manual_assets table), with a scope split.

Two features were hiding here. This issue keeps the simple case — inventory records with no network identity (spare laptop, desk phone, non-networked printer): no address columns, no monitoring. Anything with an IP, hostname or URL is a manual network asset and moves to #5213, where it is a hand-entered discovered_assets row that inherits everything a network device already has (monitors, alerts, SNMP, tunnels, topology, website/URL targets). Rule: has a network identity → #5213; does not → here. The two link via linked_discovered_asset_id, never merge.

Spec updated on spec/4622-manual-asset-entry. Decisions 2–7 still open (recommendations unchanged: not billable, site required, no custom fields in v1, link only, no CSV in v1, org contacts as assignee).