Tuckmark Agent Import

Tuckmark Agent Import

Use the released tuckmark CLI. Tuckmark itself does not parse order files, invoke an LLM, or automate a browser.

Privacy Boundary

• Keep the original order export and product-page body local. Do not commit, upload, attach, log, or put either in a proposal.
• Use only a concise source note that the user approves. Never include account data, addresses, order numbers, or the session secret.
• Open a product page only in the user's already-authorized browser context. Stop for login, CAPTCHA, 2FA, payment, or any other identity challenge.

Workflow

1. Resolve the named DEVD instance. Pass --instance <name> or set TUCKMARK_DEVD_INSTANCE; the command fails without one. The CLI uses local Unix socket / Named Pipe IPC and does not accept a DEVD URL or data directory.

2. Read only the Agent recommendation catalog and current inventory:

   tuckmark agent-import catalog --instance "$DEVD_INSTANCE"
   tuckmark agent-import inventory --instance "$DEVD_INSTANCE" --query "<model or keyword>"
   

   Catalog results include only system and shared-directory templates. recommendedUse is an optional human-readable suggested use; for new materials, use the material evidence to select and order up to three suitable templates. An absent suggestion means the template remains usable but is not a default recommendation.

3. Interpret the order outside Tuckmark. Decide material identity yourself; do not run name matching that silently converts a new item into a restock. Use kind: "restock" only with the exact targetMaterialId returned by inventory. Include that material's updatedAt as targetMaterialUpdatedAt.

4. Add needsAttention when identity, quantity, suffix, packaging, or other factual evidence is uncertain. It is non-blocking: do not force the user to certify the match.

5. Build a local, temporary tuckmark.agent-import.v1 proposal. New items must have one default template, up to two ordered alternatives, positive inventory quantity, positive labelPrintQuantity, and material fields. description is the concise overview; deviceDetails is one Markdown string for factual device details. Do not turn that detail into a key-value object or manufacture attributes from incomplete evidence. Derive label quantity from storage packages or independently labeled units; never copy the inventory quantity blindly. Restocks must keep template absent.

   {
     "schema": "tuckmark.agent-import.v1",
     "sourceNote": "purchase receipt",
     "items": [{
       "id": "agent-local-item-1",
       "kind": "new",
       "selected": true,
       "quantity": 100,
       "labelPrintQuantity": 1,
       "material": {
         "fullName": "Example IC",
          "description": "Single-line overview",
          "deviceDetails": "- Verified feature\n- Package evidence",
         "packagingRemark": "reel"
       },
       "sourceNote": "purchase receipt",
       "template": { "source": "system", "id": "cable-tag", "name": "Cable Tag", "fields": [] },
       "templateAlternatives": [],
       "templateInput": {},
       "revision": 0,
       "pendingTemplateEventId": null
     }]
   }
   

6. Create the session. The CLI opens the confirmation page unless --no-open is supplied. It prints a session ID and permission-restricted credential-file path, never the secret.

   tuckmark agent-import create --file /tmp/proposal.json --instance "$DEVD_INSTANCE"
   

7. Wait for user changes. If the user switches a new-material template, DEVD creates a field-contract event and freezes only that label panel. Poll and fulfill the exact event revision:

   tuckmark agent-import wait --session <session-id> --instance "$DEVD_INSTANCE"
   tuckmark agent-import fulfill --session <session-id> --event <event-id> --revision <revision> \
     --input '{"field":"value"}' --instance "$DEVD_INSTANCE"
   

   Do not fulfill an event with guessed fields. A stale revision is rejected; refresh with wait, regenerate values for the new field contract, and continue waiting.

8. Do not confirm on the user's behalf. The user reviews, edits, selects items, and confirms in the Web App. Sessions expire after 30 minutes.