@seeed-studio/sensecraft-cli 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,12 +1,18 @@
1
- # Manifest reference — `sensecraft-app.json`
1
+ # Manifest reference — `codecraft-app.json`
2
2
 
3
- The manifest is the local source of truth for one SenseCraft app. It is **not** the CLI payload verbatim: it carries local-only bookkeeping (paths, hashes, sync state) that must be stripped when building `--from-json` bodies.
3
+ The manifest is the local source of truth for one CodeCraft Hub app. It is **not** the CLI payload verbatim: it carries local-only bookkeeping (paths, hashes, sync state) that must be stripped when building `--from-json` bodies.
4
+
5
+ Read this contract and the template before constructing a manifest or payload. First read [app-fields.md](../../references/app-fields.md) for info/BOM, [tool-blocks.md](../../references/tool-blocks.md) for deployment, and [content-review.md](content-review.md) for human-facing copy. Serialization follows project discovery and resolution of material decisions.
4
6
 
5
7
  Top-level sections: `manifest_version`, `identity`, `info`, `images`, `deployment`, `bom`, `sync`.
6
8
 
9
+ Canonical filename: `codecraft-app.json`, or `codecraft-app.<slug>.json` for multiple apps. Legacy `sensecraft-app.json` / `sensecraft-app.<slug>.json` files remain discoverable and migrate by filename only; preserve app identity and sync state, carry forward review notes and any retained baseline under the new stem without overwriting existing files, and leave historical snapshots intact. This naming change does not change `manifest_version` or the API payload.
10
+
11
+ The template is an unfilled scaffold: null permission choices must be resolved from the user/session; empty images/blocks do not propose a cover or deployment plan. It is not ready to submit. Keep evidence, decisions, BOM query/selected catalog results, artifact paths/hashes and review findings in `.sensecraft/<manifest-stem>.review.md`. This sidecar is local-only and never projected into API fields. Final app values belong only in the canonical manifest.
12
+
7
13
  ## `manifest_version`
8
14
 
9
- Integer, currently `1`. Bump only when the schema changes shape.
15
+ Integer, currently `1`. Optional backward-compatible fields such as `info.activity_id` do not require migration; older version-1 manifests may omit them. Bump the version for an incompatible required shape or interpretation change.
10
16
 
11
17
  ## `identity` — which remote app, which account
12
18
 
@@ -15,23 +21,32 @@ Integer, currently `1`. Bump only when the schema changes shape.
15
21
  | `app_id` | after create | `null` until created. Once set, NEVER re-run create for this manifest |
16
22
  | `remote_type` | preflight | `Global` / `China` / `Private` from `auth info`. Update flow hard-stops on mismatch. CodeCraft Hub requires Global; China supports SenseCraft Data only |
17
23
  | `org_id` | preflight | from `auth info` |
18
- | `account` | preflight | from `auth info` |
24
+ | `account` | preflight | account reported by the completed auth wizard or otherwise verified for this profile; `auth info` does not show it. Keep `null` if unknown |
19
25
  | `created_at` | after create | **Local UTC timestamp recorded when create succeeds** — the CLI returns no created time |
20
26
 
21
27
  ## `info` — app info gate fields
22
28
 
23
29
  | Key | Rule |
24
30
  |-----|------|
25
- | `app_name` | non-empty, ≤ 60 UTF-16 code units |
26
- | `excerpt` | non-empty, ≤ 300 UTF-16 code units |
31
+ | `app_name` | non-empty string, ≤ 60 UTF-16 code units |
32
+ | `excerpt` | non-empty string, ≤ 300 UTF-16 code units |
27
33
  | `scene` | string id from `app_scenarios_array` (`sensecraft-cli model constants`) |
28
34
  | `license` | string, may be `""` |
29
- | `author` | string; default the `auth info` account |
30
- | `allow_clone` | `0` or `1` only |
31
- | `allow_commerce` | `0` or `1` only |
35
+ | `author` | string; use the authenticated account when established, or an explicitly chosen author; otherwise `""`. Do not invent an account from `auth info` |
36
+ | `allow_clone` | integer `0` or `1` only in the canonical manifest; no implicit default |
37
+ | `allow_commerce` | integer `0` or `1` only in the canonical manifest; no implicit default |
38
+ | `activity_id` | optional positive integer from the current `app activity list`, within the CLI's int64 range. `null`/absent means no join selected for a new app; never use `0` or a string |
32
39
 
33
40
  Full field compliance: [../../references/app-fields.md](../../references/app-fields.md).
34
41
 
42
+ ### Activity selection and participation
43
+
44
+ Read [activity selection guidance](../../references/app-fields.md#activity-selection-during-app-authoring) before filling `info.activity_id`. Use project facts and the API/guide requirements to choose a suitable activity or none; ask with candidate options plus no activity when the decision is uncertain. The template's `null` is an unselected optional field, not a reason to skip the assessment. Record the activity name/ID, time window, rules/guide links, fit or gaps, and rationale in review notes.
45
+
46
+ Project `info.activity_id` to top-level `activity_id` on the initial create, or when an update/resume intentionally joins an activity. Always preserve the explicit clone/commercial flags; resolve any conflict with activity requirements rather than relying on the CLI's implicit clone opt-in. Recheck the current API list before submitting. After success, retain the selection as local metadata and record the join result separately in review notes; routine edits must not resend a historical ID. Omission/null on an update preserves existing participation and does not leave an activity. Leaving is an explicit `cancel_activity_id` operation in the parent workflow.
47
+
48
+ `activity_id` is a join instruction, not a scalar that `app view` is guaranteed to echo. Check any exposed saved activity association, but do not claim participation verified if the response lacks it. Keep selection/submission evidence separately from the content drift baseline. Association also does not establish that a competition entry meets all submission or publication requirements.
49
+
35
50
  ## `images` — local paths with upload state
36
51
 
37
52
  Array, order matters: **index 0 is the cover** (becomes `pic_url`). Up to 16 entries. May be empty at create time — a private draft works without images; a cover is required before publishing.
@@ -47,32 +62,39 @@ Formats JPG/JPEG/PNG/GIF/WebP, ≤ 5 MB each, prefer 4:3. SVG is rejected by the
47
62
 
48
63
  ## `deployment.blocks`
49
64
 
50
- Flat ordered array, copied through to the payload unchanged. Blocks before the first `step` = introduction; each `step` starts a deploy step. Tool-block configs (`flash-firmware`, `deploy-ai-model`, …): [../../references/tool-blocks.md](../../references/tool-blocks.md). After `file upload --type 4`, put the URL on the `flash-firmware` block as flat `firmware_url` (plus `firmware_name` and string `firmware_size`). Do not nest those fields under `config`. The editor wraps them into `config` when the doc is opened.
65
+ Flat ordered array, copied through to the payload unchanged. Blocks before the first `step` = introduction; each `step` starts a deploy step. Read [../../references/tool-blocks.md](../../references/tool-blocks.md) before selecting or configuring tools. After `file upload --type 4`, put the URL on the `flash-firmware` block as flat `firmware_url` (plus `firmware_name` and string `firmware_size`). Do not nest those fields under `config`. The editor wraps them into `config` when the doc is opened. A needed block with missing inputs may stay in a local draft, but the app is not deployment-ready until those inputs have a usable path; mark gaps in review notes rather than inventing URLs or IDs.
51
66
 
52
67
  ## `bom.materials`
53
68
 
54
- Seeed catalog rows carry `id` (SKU), `quantity`, `name`, `note`, `buy_url` — never `price`/`pic_url` (resolved by SKU server-side). Custom rows carry `name` + `quantity` (required) and optionally `note` / `buy_url` — no `id`, no image, no price. Details: [../../references/app-fields.md](../../references/app-fields.md#bom-materials).
69
+ Seeed catalog rows carry `id` (SKU), `quantity`, `name`, `note`, `buy_url` — never `price`/`pic_url` (resolved by SKU server-side). Set `id` from the live `app bom search` result's `sku`, not an internal product ID. Preserve the lookup evidence in review notes. Custom rows carry `name` + `quantity` (required) and optionally `note` / `buy_url` — no `id`, no image, no price. Read [catalog verification and BOM fields](../../references/app-fields.md#catalog-verification-before-authoring-a-bom) before writing rows; custom entries are not API-confirmed catalog products.
70
+
71
+ Names are non-empty strings and quantities are positive integer strings such as `"1"`. A custom row omits `id` entirely; `"id": null` is not a custom row. Notes and purchase URLs, when supplied, are strings; an optional empty purchase URL is allowed, but a non-empty one must be HTTP(S). Local shape validation cannot prove a catalog match or the correct quantity.
55
72
 
56
73
  ## `sync` — local vs remote bookkeeping
57
74
 
58
75
  | Key | Notes |
59
76
  |-----|-------|
60
- | `local_revision` | integer, `+1` on every local edit after creation of the manifest |
61
- | `last_pushed_revision` | `local_revision` value as of the last successful create/push. `0` + set `app_id` = half-finished create → resume via update |
62
- | `last_pushed_at` | RFC3339 of last successful push |
63
- | `last_pushed_hash` | drift baseline — see the pinned algorithm below |
77
+ | `local_revision` | positive integer; increment once per logical batch of app-content/asset changes. Updating identity, upload bookkeeping within that batch, or sync metadata does not itself create another revision |
78
+ | `last_pushed_revision` | `local_revision` at the last verified complete push. `0` + set `app_id` = half-finished create → resume via update |
79
+ | `last_pushed_at` | RFC3339 timestamp with timezone of the last verified complete push, or `null` before one |
80
+ | `last_pushed_hash` | full `sha256:<64 lowercase hex digits>` digest of the retained verified baseline, or `null` before one |
81
+
82
+ ### Retain the comparison baseline
83
+
84
+ A hash alone cannot support field-level diffs or a three-way merge after local edits. After verifying the saved sketch and BOM, retain the exact normalized comparison object in `.sensecraft/<manifest-stem>.baseline.json`. This file is the last verified snapshot, not the current app source. Preserve it between sessions; keep it out of the API payload. Updating the review notes must not destroy the baseline.
64
85
 
65
- **`last_pushed_hash` algorithm** (compute exactly this way so every session reproduces the same baseline):
86
+ Build that object as `{"info": {...}, "images": ["<URL>", ...], "deployment": {...}, "materials": [...]}` using the stable info fields (`app_name`, `excerpt`, `scene`, `license`, `author`, `allow_clone`, `allow_commerce`), ordered image URLs, complete deployment, and BOM. Exclude the optional join instruction `activity_id` from this `info` projection; review notes retain that action's evidence/result. Accept only understood server normalization; reconcile it into the canonical manifest before recording success. Compare normalized saved values with the intended values first. A partial save or unresolved difference must not advance `last_pushed_*` or replace the baseline.
66
87
 
67
- 1. Build the projection object `{"info": {...}, "images": ["<file_url>", ...], "deployment": {...}, "materials": [...]}` from the pushed payload — derived keys like `pic_url` are **excluded** (the hash covers the source fields, not derived duplicates).
68
- 2. Serialize as canonical JSON: UTF-8, keys sorted, no insignificant whitespace (Python: `json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`).
69
- 3. `last_pushed_hash = "sha256:" + hex(SHA-256 of those bytes)`.
88
+ **Hash algorithm:** serialize the comparison object as UTF-8 canonical JSON with sorted keys, no insignificant whitespace, and Unicode preserved (`json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`). Hash those bytes with SHA-256 and prefix the full hexadecimal digest with `sha256:`. Array order is significant.
70
89
 
71
- On the drift check, apply the same projection to the `app view --sketch` response before hashing, with these equivalence rules:
90
+ ### Compare on update or resume
72
91
 
73
- - **Same key set**: a key absent from the remote view is dropped from **both** sides before hashing (server-normalized views may omit keys).
74
- - **Type normalization**: coerce values to the manifest's forms — e.g. a remote `"scene": 1` (number) compares as `"1"` (string).
75
- - **Derived keys excluded** on both sides (`pic_url`, `app_id`, timestamps, review/lifecycle fields like `be_public`).
92
+ 1. Load the retained baseline and check its digest against `sync.last_pushed_hash`. Compare it with the current local projection and the latest remote sketch/BOM to identify local changes, remote changes, and real conflicts.
93
+ 2. Normalize equivalent representations consistently: numeric scene/SKU/device-type/size/quantity values to their canonical strings; clone/commercial flags to integers; image objects to URL strings. For `flash-firmware` only, flatten editor-wrapped `config` back onto the block, retaining its fields. Keep other tool configs nested. Treat missing optional empty note/URL strings consistently. Preserve block, image, and BOM order and every substantive tool field.
94
+ 3. Exclude the `activity_id` join instruction, derived duplicates (`pic_url`, top-level Node-RED mirrors), and unrelated identity/lifecycle/timestamp fields from all content-drift projections. Assess any intentional participation change separately, using review evidence and the current activity rules. Do not drop a non-empty stable managed field from both sides merely because a remote response omitted it; that is a verification gap to resolve. Do not normalize away a new/deleted/reordered block, a changed URL, or an unknown substantive field.
95
+ 4. If an old manifest has only a hash and no retained baseline, recover it from a trusted last-pushed snapshot when possible. Otherwise inspect the remote and present the concrete differences for reconciliation before writing. Do not use the already-edited local manifest as an assumed old baseline.
96
+
97
+ Only a verified complete create/update replaces the retained baseline and advances `last_pushed_*`. Keep successful upload URLs and known app IDs after partial failures so the next run resumes the same app.
76
98
 
77
99
  ## Manifest → CLI payload
78
100
 
@@ -80,17 +102,28 @@ Build `--from-json` bodies by projection — keep server fields, drop local-only
80
102
 
81
103
  | Manifest | Payload key |
82
104
  |----------|-------------|
83
- | `info.*` | same names at top level |
105
+ | `info.*` except `activity_id` | same names at top level |
106
+ | `info.activity_id` | top-level positive integer `activity_id` on initial create or an intentional join/resume. Null/absent → omit the key entirely. Routine update → omit even if a historical selection is retained |
84
107
  | `images[].file_url` (in order) | `images` (array of URLs); `pic_url` = first element. **Empty → omit both keys entirely** — the info gate rejects `images: []`, but accepts the key being absent |
85
108
  | `deployment` | `deployment` |
86
109
  | `bom.materials` | `materials` |
110
+ | `node-red` block `config.flow_data` | additionally derive top-level `flow_data` as a JSON **string**, when present |
111
+ | `node-red` block `config.model_data` | additionally copy top-level `model_data` as an object, when present |
87
112
  | `identity`, `sync`, `images[].path/sha256/role`, `manifest_version` | **never sent** |
88
113
 
89
- Never include `be_public` / `privacy` in any payload.
114
+ Node-RED mirrors are derived at projection time, not stored as competing top-level manifest values. If several Node-RED blocks have conflicting flow/model snapshots, resolve which one should supply the app-level mirrors before uploading. Read the Node-RED section of the tool-block reference first.
115
+
116
+ Never include `be_public` / `privacy` in any payload, or local review/baseline data. Populate pending upload URLs in the canonical manifest before generating a payload; do not send null image URLs or local filesystem paths as remote URLs.
117
+
118
+ ## Local validation and its limits
119
+
120
+ Run `python3 <skill-dir>/assets/validate_manifest.py <manifest> --scene-ids <actual-comma-separated-ids>` before uploads and again after inserting upload URLs. It rejects malformed sections, unsupported versions, incorrect canonical field types, invalid image/BOM/block shapes, raw Markdown in prose blocks, and recognizable credential values without echoing them. Missing images or pending tool inputs can be warnings; a warning-bearing pass does not establish deployment readiness.
121
+
122
+ The helper intentionally uses a conservative UTF-16 budget for names/excerpts; the current Go CLI counts Unicode code points. It checks file extensions/size/hash for images, not their visual content. It checks the optional activity ID's numeric shape, not whether the activity is open, suitable, or joined. It does not contact an API, confirm catalog products or scene freshness, scan firmware/archive bytes, prove device compatibility, validate every tool-specific config, or perform the editorial review. Those checks remain part of the discovery/review/upload workflow.
90
123
 
91
124
  ## Worked example
92
125
 
93
- See [../assets/manifest-template.json](../assets/manifest-template.json) for a fresh manifest (pre-create), and below for the same manifest after a successful create:
126
+ The template is a blank scaffold; the snapshot below illustrates a filled, coverless manifest. It describes a fictional timer: IDs, scene, permissions, device/product matches, and URLs must be resolved for the actual project. The reserved `.invalid` URLs deliberately cannot serve artifacts and are **not** an upload-ready result or evidence of API confirmation. The full digest is computed from this example's comparison projection, which would also be retained in the baseline file after a verified real push.
94
127
 
95
128
  ```json
96
129
  {
@@ -98,62 +131,88 @@ See [../assets/manifest-template.json](../assets/manifest-template.json) for a f
98
131
  "identity": {
99
132
  "app_id": "12345",
100
133
  "remote_type": "Global",
101
- "org_id": "org-9",
134
+ "org_id": "example-org",
102
135
  "account": "maker@example.com",
103
- "created_at": "2026-10-20T08:30:00Z"
136
+ "created_at": "2026-10-28T08:00:00Z"
104
137
  },
105
138
  "info": {
106
- "app_name": "Jar Lid Counter",
107
- "excerpt": "Counts screw-cap jars on a conveyor with a XIAO ESP32S3 Sense and a FOMO model.",
108
- "scene": "7",
139
+ "app_name": "Lap Timer",
140
+ "excerpt": "Time laps with physical buttons and read elapsed time on the Wio Terminal display.",
141
+ "scene": "5",
109
142
  "license": "MIT",
110
143
  "author": "maker@example.com",
111
144
  "allow_clone": 1,
112
- "allow_commerce": 0
145
+ "allow_commerce": 0,
146
+ "activity_id": null
113
147
  },
114
- "images": [
115
- {
116
- "path": "docs/images/cover.png",
117
- "sha256": "b5bb9d…",
118
- "file_url": "https://files.seeedstudio.com/…/cover.png",
119
- "role": "cover"
120
- }
121
- ],
148
+ "images": [],
122
149
  "deployment": {
123
150
  "blocks": [
124
- { "id": "intro_1", "type": "paragraph", "content": "What this app does.", "indent": 0 },
125
- { "id": "step_1", "type": "step", "title": "Flash firmware", "content": "Flash firmware", "expanded": true, "indent": 0 },
151
+ {
152
+ "id": "intro_1",
153
+ "type": "paragraph",
154
+ "content": "The timer runs on the board and shows elapsed time on its display.",
155
+ "indent": 0
156
+ },
157
+ {
158
+ "id": "step_1",
159
+ "type": "step",
160
+ "title": "Flash the timer",
161
+ "content": "Flash the timer",
162
+ "expanded": true,
163
+ "indent": 0
164
+ },
165
+ {
166
+ "id": "para_1",
167
+ "type": "paragraph",
168
+ "content": "Connect the Wio Terminal over USB, then use the firmware tool below.",
169
+ "indent": 0
170
+ },
126
171
  {
127
172
  "id": "ff_1",
128
173
  "type": "flash-firmware",
129
- "device_id": "113991115",
130
- "device_type": "32",
174
+ "device_id": "102991299",
175
+ "device_type": "",
131
176
  "flash_mode": "bin",
132
- "firmware_url": "https://files.seeedstudio.com/…/firmware.bin",
133
- "firmware_name": "firmware.bin",
177
+ "firmware_url": "https://files.example.invalid/lap-timer.bin",
178
+ "firmware_name": "lap-timer.bin",
134
179
  "firmware_size": "412316",
135
- "flash_address": "0x0",
180
+ "flash_address": "0x4000",
136
181
  "muse_gadget": false,
137
182
  "full_flash": false
183
+ },
184
+ {
185
+ "id": "step_2",
186
+ "type": "step",
187
+ "title": "Time a lap",
188
+ "content": "Time a lap",
189
+ "expanded": true,
190
+ "indent": 0
191
+ },
192
+ {
193
+ "id": "para_2",
194
+ "type": "paragraph",
195
+ "content": "Restart the board. Press the start button to run the timer and the lap button to record an elapsed time on the display.",
196
+ "indent": 0
138
197
  }
139
198
  ]
140
199
  },
141
200
  "bom": {
142
201
  "materials": [
143
202
  {
144
- "id": "113991115",
203
+ "id": "102991299",
204
+ "name": "Wio Terminal",
145
205
  "quantity": "1",
146
- "name": "Seeed Studio XIAO ESP32S3 Sense",
147
- "note": "Main MCU",
148
- "buy_url": "https://www.seeedstudio.com/"
206
+ "note": "Runs the timer and displays elapsed time",
207
+ "buy_url": "https://shop.example.invalid/wio-terminal"
149
208
  }
150
209
  ]
151
210
  },
152
211
  "sync": {
153
212
  "local_revision": 1,
154
213
  "last_pushed_revision": 1,
155
- "last_pushed_at": "2026-10-20T08:31:02Z",
156
- "last_pushed_hash": "sha256:9f2c…"
214
+ "last_pushed_at": "2026-10-28T08:01:00Z",
215
+ "last_pushed_hash": "sha256:880e59411f09e0e462e0bc10e160fe344b91c576bf8fe886d44eb6cce5f31261"
157
216
  }
158
217
  }
159
218
  ```
@@ -0,0 +1,56 @@
1
+ # Project discovery before app authoring
2
+
3
+ The discovery result must explain what the project actually does and how a new user can deploy and use it. Collect enough evidence for the app's fields, tool configs, BOM, and copy before presenting decisions. Scale inspection to the project; exhaustive source review is unnecessary, but reading only its title and package metadata is insufficient.
4
+
5
+ ## Inspect the actual project
6
+
7
+ Start with the conversation's established choices. Locate files with `rg --files`, then read the relevant files themselves. Skip dependency caches and generated trees unless they contain the deployment artifact. Use targeted source searches to check implementation claims; do not treat matching filenames as evidence of functionality.
8
+
9
+ The agent handles CLI inspection and auth setup through the [parent auth workflow](../../SKILL.md#auth). If authentication is missing, start the interactive flow yourself and continue independent file inspection while the user completes browser authorization; do not give them command-line setup tasks. `auth info` shows site/org/Key ID, not an account name. Use the completed wizard's account identity when available and leave unknown identity metadata unset.
10
+
11
+ | Question to resolve | Useful evidence | Affects |
12
+ |---|---|---|
13
+ | What problem does it solve, for whom, with what output? | Conversation, README, user docs, demo/screenshots, implemented entry points | Name, excerpt, scene, introduction |
14
+ | Which features exist now, and which are plans/examples? | Runtime code, routes/screens, tests, documented limitations | Claims and scope of copy |
15
+ | What must a user have or connect? | Hardware docs, wiring diagrams, board configs, model/device compatibility | BOM, prerequisites, target tool |
16
+ | What runs on each component? | Firmware configs, package scripts, Dockerfile/compose, Node-RED JSON, Blockly project reference | End-to-end deployment plan |
17
+ | Which exact deployable inputs exist? | Build output/release files, artifact metadata, target board/architecture and version | Firmware/model/container/flow config |
18
+ | How does a first-time user configure, start, check success, and stop/reset it? | Runtime setup UI, configuration schema, code and user docs | Ordered instructions and expected results |
19
+ | What is required outside the page? | Accounts/services, network, peripherals, browser/USB prerequisites | Feasibility and user decisions |
20
+ | What may be distributed? | LICENSE and artifact-specific notices, config examples, image origins | License, assets, clean artifact selection |
21
+ | Does the project fit an open activity or competition? | Verified purpose/hardware/features, existing user preferences, live activity list and API-provided rules/guides | Activity selection or none, eligibility gaps, required deliverables and permission choices |
22
+ | What is the existing remote identity and local history? | Manifest, git state, auth output, prior sync/review notes | Create vs update, environment, duplicate prevention |
23
+
24
+ Inspect configuration **names and mechanisms**, not secret values. A `.env.example` may describe user inputs; a populated `.env`, credential store, or private key is not upload material. Review distributable archives and binaries too, since a build can embed credentials.
25
+
26
+ For each prospective asset/artifact, record its relative path, role, existence, byte size, SHA-256, target/architecture when relevant, and intended block/field. Do not upload a whole repo just because the request says “upload my project”: select the deployable artifacts the supported tools actually consume.
27
+
28
+ ## Separate facts, proposals, and unresolved choices
29
+
30
+ Maintain concise notes in `.sensecraft/<manifest-stem>.review.md`:
31
+
32
+ | Item | Evidence | Status / next action |
33
+ |---|---|---|
34
+ | Project capability or field candidate | File/section, implementation location, or explicit user decision | Verified, proposed, contradicted, or unknown |
35
+ | Deployment action | Supported tool + actual artifact/config source | Ready, planned upload, user input at deployment, or blocked |
36
+ | BOM item | Project requirement and actual catalog query/selected result | API-confirmed, custom, ambiguous, or unverified |
37
+ | Activity decision | Activity API row and guide/rules, dates, project evidence and user preferences | Selected with reason, no fit, uncertain eligibility/choice, or lookup unavailable; record join outcome after upload |
38
+
39
+ “Verified” means the evidence supports that specific statement. The presence of a camera library does not prove object counting. A Dockerfile does not prove a Fleet app ID or supported platform integration. A board family name does not establish the exact SKU, `uniform_type`, or flash address.
40
+
41
+ User input required at **deployment time** can be a valid supported path (for example a tool's documented prompt for a personal token). Explain that prompt without distributing the token. An authoring-time missing artifact or unknown device target remains a gap.
42
+
43
+ When docs and code disagree, inspect enough to identify the conflict. Use established user intent and implementation evidence to propose a resolution. Ask if the conflict changes the app promise, supported device, deployment path, permission, or distributed artifact; do not silently turn uncertain claims into polished facts.
44
+
45
+ ## Ask after discovery has made the choice concrete
46
+
47
+ Read the field and tool-block references before proposing options. After discovery, run `app activity list` and read the guides/rules for plausible activities per [app-fields.md](../../references/app-fields.md#activity-selection-during-app-authoring); the public activity list does not need an Access Key. Use the gathered project facts to choose a clear fit or none, and ask only when the fit or choice is uncertain. After the agent establishes auth, resolve scene IDs and BOM catalog candidates through the real CLI reads. Record the queries, selected results, source links, and lookup time; offline/sandbox data is not live confirmation. Then batch remaining decisions with a recommendation and a short reason. Typical questions concern:
48
+
49
+ - Product framing or language when the conversation and project do not establish it.
50
+ - Clone and commercial-use choices; a project license alone does not answer these platform settings.
51
+ - Activity options plus no participation when eligibility, missing requirements, or the best candidate is uncertain. Include actual dates, rules and project fit; do not ask a generic opt-in question for every new app.
52
+ - Similar hardware variants, optional accessories, unknown quantities, or a custom product fallback.
53
+ - Missing deployable files, an unsupported action, or a choice to upload an explicitly incomplete draft.
54
+ - Cover selection or an asset with unclear redistribution rights.
55
+
56
+ Do not re-ask known answers, ask the user to supply information already in the project, or block unrelated local work while waiting. A proposed default is a recommendation, not a recorded user decision.
@@ -8,9 +8,11 @@ Target binary: `sensecraft-cli` (this repo). Auth: active **SenseCAP Access Key*
8
8
 
9
9
  ```bash
10
10
  sensecraft-cli auth info
11
- sensecraft-cli auth init # user only, interactive
11
+ sensecraft-cli auth init --site Global --no-wait # split flow; see SKILL.md
12
12
  ```
13
13
 
14
+ Follow the [parent auth workflow](../SKILL.md#auth): the agent handles terminal prompts, the user completes browser authorization, then the agent rechecks auth. Do not ask the user to run CLI commands.
15
+
14
16
  ## Commands
15
17
 
16
18
  ### `app list`
@@ -206,6 +208,8 @@ sensecraft-cli app delete --id <app_id> --yes
206
208
  sensecraft-cli app activity list
207
209
  ```
208
210
 
211
+ The returned `guide_url` is the source for requirements and official rules; requirements are not included as a structured CLI field. Read candidate guides and compare them with the project before selecting an activity. Follow [activity selection during authoring](app-fields.md#activity-selection-during-app-authoring) for choosing a match, choosing none, or asking the user with options. Do not confuse `priority_activity_id` (list ordering) with `activity_id` (joining).
212
+
209
213
  ### `app like` / `app unlike` / `app collect` / `app uncollect` / `app mark-deploy` (L2)
210
214
 
211
215
  **Status: implemented.** `POST /flow/app/v2/mark_app`.
@@ -241,7 +245,7 @@ sensecraft-cli app clone --id <source_app_id> --name "New name" --yes
241
245
  | Subcommand | Notes |
242
246
  | ---------------------------- | ---------------------------------------------------- |
243
247
  | `search [--name]` | `get_production_options` → filter `material_options` |
244
- | `list --id` | materials from `view_app` |
248
+ | `list --id [--sketch]` | materials from `view_app`; use `--sketch` to verify saved draft rows |
245
249
  | `set --id --from-json --yes` | `update_app` materials[] (L2) |
246
250
 
247
251
  ```bash
@@ -21,6 +21,28 @@ Agent fill-in guide for SenseCraft custom apps (v3). Aligns with Console `infoFo
21
21
  | `cancel_activity_id` | positive integer | no | Leave this activity. Omit or send blank to leave participation unchanged. CLI sends a JSON number and does not change `allow_clone`. Must not equal `activity_id`. |
22
22
  | `flow_data` / `model_data` | Node-RED sync | only with `node-red` block | Block `config.flow_data` and `config.model_data` are objects, not strings. On save the app writes `JSON.stringify(config.flow_data)` to this top-level `flow_data` string and copies `model_data` here. |
23
23
 
24
+ ### Activity selection during app authoring
25
+
26
+ For a new app, assess participation using the project discovery results; do not wait for the user to name a competition. Respect any established preference to join or skip one. Run:
27
+
28
+ ```bash
29
+ sensecraft-cli app activity list
30
+ ```
31
+
32
+ Read [the activity command reference](app-commands.md#app-activity-list) before using the result. The current CLI returns `activity_id`, `name`, UTC `start_time`/`end_time`, and `guide_url` for activities open now. It does **not** return a structured requirements field. Open and read the API-provided guide for each plausible candidate, including its official rules where linked, before claiming eligibility. Missing/inaccessible guidance is an information gap, not proof that there are no requirements. Do not invent an activity-detail CLI or guessed API endpoint.
33
+
34
+ Compare the documented theme, entry window/deadline, eligibility, supported/required hardware or features, required artifacts/demo/docs, and licensing/clone/commercial conditions with the actual project and settled user choices. Distinguish what the project already satisfies from deliverables still needed. A successful empty list means no currently available activity; a failed request is not an empty list. Sandbox output is not a live activity or eligibility check.
35
+
36
+ - **Clear suitable activity:** select it with a concise evidence-based reason. If several qualify and one is clearly preferable for this project, explain that choice. Do not use result order or a popular-list `priority_activity_id` as the entry decision.
37
+ - **No suitable activity:** select no participation and explain the mismatch or lack of open activities. Omit `activity_id`; do not use `0`, invent an ID, or ask a redundant opt-in question when the evidence supports the decision.
38
+ - **Uncertain choice or eligibility:** ask with concrete options: candidate names/IDs, dates with a timezone, important requirements and project fit/gaps, plus **no activity**. Recommend the best-supported option. Reuse known answers. Do not change the project's agreed permissions or invent missing eligibility facts to make an entry fit. If new permission choices or required consent are unresolved, ask about those with the activity options.
39
+
40
+ Record the chosen activity or no-activity reason, lookup time, API/guide sources, applicable rules, and project evidence in local review notes. For `create-app`, store the optional selection in `info.activity_id` and include its positive integer at payload top level on the initial one-shot create; the CLI applies it in the new app's follow-up save. Always send the resolved `allow_clone` explicitly: the CLI may otherwise turn it on when joining an activity. An explicit `allow_clone: 0` is technically preserved by the CLI, but does not establish eligibility for a contest requiring cloning.
41
+
42
+ Recheck the current list and time window just before submitting. An invalid/expired activity can reject the entire follow-up save after an app ID already exists: preserve that ID, resolve the activity choice, and resume by update rather than creating a duplicate. Verify any exposed saved association and distinguish a join request accepted by the API from verified participation. Activity association does not by itself complete entry requirements or publish the app.
43
+
44
+ For an existing app, preserve participation unless changing it is part of the requested batch. Omission/null/blank leaves participation unchanged, not removed; leaving uses `cancel_activity_id` through the parent workflow. Do not repeatedly send a historical `activity_id` during unrelated edits.
45
+
24
46
  ### Create vs update
25
47
 
26
48
  - **Create (CLI one-shot)**: `POST /flow/app/v3/create_app` then `update_app` with the rest of `--from-json` on the **new** `app_id` only — **no `--yes`**. Editing an **existing** app is `app update --yes` (L2).
@@ -45,6 +67,20 @@ API: `POST /flow/app/v3/edit_privacy_app` (CLI name: `publish` / `unpublish`).
45
67
 
46
68
  ## BOM (`materials[]`)
47
69
 
70
+ ### Catalog verification before authoring a BOM
71
+
72
+ Read this reference before writing BOM rows. Derive required devices, app-specific accessories, variants, and quantities from project evidence, then resolve catalog identity through the live API:
73
+
74
+ ```bash
75
+ sensecraft-cli app bom search --name "<product name or SKU>"
76
+ ```
77
+
78
+ The CLI filters `material_options` from `get_production_options` and returns `list[]` and `count`. Match the **exact variant**, not merely the first similar name. A result's **`sku` becomes the saved material row's `id`**; its internal product `id`, if present, is not the SKU. Copy the returned `name` and `buy_url`; derive `quantity` (string) and the app-specific `note` from the project. Do not fabricate SKU or purchase URLs from memory or examples.
79
+
80
+ Record the query and selected SKU/name/URL in local review notes, with the project evidence for quantity and purpose. Several plausible matches need a user decision. A successful no-match search after reasonable name/SKU variants permits a custom row; an auth/network/API failure leaves the candidate **unverified**, not absent from the catalog. Sandbox results are simulated and cannot confirm a real product. Report custom rows and unverified candidates separately from API-confirmed catalog rows. A project with no required hardware may use an empty BOM.
81
+
82
+ Catalog verification proves product identity; it does not prove the app saved that row. After create or BOM update, use `app bom list --id <app_id> --sketch` and compare the saved rows with the manifest.
83
+
48
84
  ### Seeed Studio catalog row
49
85
 
50
86
  | Field | Required | Notes |
@@ -6,7 +6,7 @@ Domain skill for **CodeCraft Hub applications**. Auth: **Access Key** (HTTP Basi
6
6
 
7
7
  Parent router: [`../SKILL.md`](../SKILL.md).
8
8
  SenseCAP IoT: [`data.md`](data.md).
9
- Child skill: [`../create-app/SKILL.md`](../create-app/SKILL.md) — manifest-driven app lifecycle: mine a finished local project into a versioned `sensecraft-app.json` manifest (source of truth), create the app in one go, then local-first updates with drift detection (one batch confirmation per push). Publish / unpublish / delete stay in this file.
9
+ Child skill: [`../create-app/SKILL.md`](../create-app/SKILL.md) — turn a local project into a deployable app: discover project facts, resolve uncertain decisions, write and review human-facing copy, configure tool-block deployment, confirm BOM catalog matches through the API, and build the versioned `codecraft-app.json` before upload. Read each related reference before authoring its information. Later updates follow the manifest with drift detection and one batch confirmation per push. Publish / unpublish / delete stay in this file.
10
10
 
11
11
  ## Agent rules
12
12
 
@@ -14,7 +14,7 @@ Child skill: [`../create-app/SKILL.md`](../create-app/SKILL.md) — manifest-dri
14
14
  ```bash
15
15
  sensecraft-cli auth info
16
16
  ```
17
- Need an active **SenseCAP Access Key**. If missing, ask the user to run `sensecraft-cli auth init` locally. **Never** run `auth init` for them.
17
+ Need an active **SenseCAP Access Key**. If missing, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`.
18
18
  2. **L2 confirm is a separate chat turn** ([confirmation.md](confirmation.md)) before: `publish` (`--agree-declaration`), `unpublish`, `withdraw`, `delete`, `like`, `unlike`, `collect`, `uncollect`, `mark-deploy`, `clone`, **`app update` / `bom set`**. 「删除应用 demo」is **not** confirmation — ask `将从{环境}环境删除应用 demo(ID: …)。删除后可能无法恢复。是否确认执行?`, wait for `确认`, then `--yes`. Never pass `--yes` on the same turn as the first request. **Exception — batch authoring:** [`create-app`](../create-app/SKILL.md) confirms a whole push batch (fields + images + BOM + blocks) in one turn instead of per write; its one-go `app create` needs no confirmation at all.
19
19
  **`app create` is not L2** — including `--from-json` with full fields (create + internal follow-up `update_app` on the **new** `app_id` only). Prefer one-shot create when the payload is ready. Still tell the user what will be created before running create.
20
20
  3. **Privacy values**: submit review → `privacy` / flow uses **`2`** (pending); unpublish/private → **`0`**. **Never send `1`** (ops-approved public; Admin only).
@@ -105,6 +105,8 @@ Seeed rows need `id`(=SKU). Custom rows omit `id`. No manual custom image upload
105
105
 
106
106
  ### Author path
107
107
 
108
+ For a local project/repository or an existing `codecraft-app.json`, use [create-app](../create-app/SKILL.md) for the full discovery, writing review, BOM verification, and manifest workflow. The abbreviated commands below apply to content that is already authored and reviewed; do not bypass that workflow by uploading a developer README directly.
109
+
108
110
  0. Resolve `scene`, inspect fields, and inspect block layouts:
109
111
  ```bash
110
112
  sensecraft-cli model constants
@@ -6,32 +6,54 @@ Complete reference for AI agents. All paths are relative to the OpenAPI base URL
6
6
 
7
7
  ## auth init
8
8
 
9
- Interactive setup wizard (OAuth Device Flow). Obtains an Access Key and writes `sensecraft.json`.
9
+ OAuth Device Flow. Obtains an Access Key and writes `sensecraft.json`.
10
10
 
11
- **Not an OpenAPI call.** Requires interactive terminal (TTY) unless using sandbox mode.
11
+ **Not an OpenAPI call.** Bare `auth init` is a TTY wizard. The split flags below are for a one-shot shell: each command prints JSON and exits. `--sandbox` simulates the wizard, or the one split step it is combined with, without network access.
12
12
 
13
13
  ### Flags
14
14
 
15
15
  | Flag | Required | Default | Description |
16
16
  |------|----------|---------|-------------|
17
- | `--sandbox` | No | `false` | Simulate the full wizard without sending real network requests |
17
+ | `--sandbox` | No | `false` | Simulate this step without sending real requests |
18
+ | `--site` | With `--no-wait` | — | `Global` or `China`. China is SenseCraft Data only |
19
+ | `--no-wait` | No | `false` | Request a device code and return immediately |
20
+ | `--device-code` | No | — | Continue a previous `--no-wait` login |
21
+ | `--key-id` | No | — | Save this existing Access Key id after authorization |
22
+ | `--label` | No | — | Create an Access Key with this label after authorization |
23
+ | `--access-level` | No | `read-write` | With `--label`: `read-write` or `only-read` |
24
+ | `--json` | No | `false` | Accepted for agents. The split flow always prints JSON |
18
25
 
19
- ### Wizard steps
26
+ ### Wizard
27
+
28
+ With no split flags, in a terminal:
20
29
 
21
30
  1. Select site: Global (International) or China. China supports SenseCraft Data only. SenseCraft AI and CodeCraft Hub require Global.
22
- 2. Browser OAuth Device Flow authorization
23
- 3. Organization selection
24
- 4. Access Key creation
25
- 5. Save to local config and set as active profile
31
+ 2. Request a device authorization code and show the verification URL/code.
32
+ 3. Wait for the user to approve in the browser; the CLI polls automatically.
33
+ 4. Select an existing Access Key, or create one with a label and permission level.
34
+ 5. Save to local config and set it active.
26
35
 
27
- ### Output
36
+ ### Split flow
28
37
 
29
- Human-readable progress on stdout/stderr. No JSON payload.
38
+ ```bash
39
+ sensecraft-cli auth init --site Global --no-wait
40
+ sensecraft-cli auth init --device-code <device_code>
41
+ sensecraft-cli auth init --device-code <device_code> --key-id <access_id>
42
+ sensecraft-cli auth init --device-code <device_code> --label <name> --access-level read-write
43
+ ```
44
+
45
+ 1. `--no-wait` prints `verification_url`, `user_code`, `device_code`, `expires_in`, and `site`, then exits. It does not read stdin.
46
+ 2. Show `verification_url` to the user and end the turn. Do not poll in that same turn.
47
+ 3. After the user authorizes, `--device-code` polls, then prints the account and Access Key list (`label`, `access_id`, `access_level`).
48
+ 4. A later command with `--key-id` or `--label` saves the key and sets it active.
49
+
50
+ The login access token is written to `sensecraft-auth-pending.json` next to the config file (mode `0600`) and is removed after the key is saved. It is not printed. Key secrets are not printed.
30
51
 
31
52
  ### Agent notes
32
53
 
33
- - Do **not** run on behalf of the user in non-interactive environments.
34
- - In sandbox mode, simulated credentials are written locally for testing.
54
+ - Do **not** run bare `auth init` in a non-interactive shell.
55
+ - Run the split commands above. Do not echo `access_token` or `access_key`.
56
+ - In sandbox mode, simulated credentials are written locally for testing. Use an isolated test config; sandbox credentials do not authorize real cloud calls.
35
57
 
36
58
  ---
37
59
 
@@ -95,7 +117,7 @@ When uninitialized:
95
117
  ```
96
118
  Config file: /path/to/sensecraft.json
97
119
 
98
- No Access Key configured yet. Run: sensecraft-cli auth init
120
+ No Access Key configured. Run: sensecraft-cli auth init --site Global --no-wait. Show verification_url to the user unchanged and end this turn. After they authorize, run the --device-code command from that command's hint.
99
121
  ```
100
122
 
101
123
  ---
@@ -26,9 +26,7 @@ Requires Node.js >= 16.
26
26
  ```bash
27
27
  sensecraft-cli auth info
28
28
  ```
29
- 2. **Never run `auth init` on behalf of the user** — it requires browser OAuth in an interactive terminal.
30
- - SenseCAP Access Key: `sensecraft-cli auth init`
31
- - If the user already has Key ID / Access Key, guide them to run `auth add` locally instead (do not pass secrets into the agent context).
29
+ 2. **Do not run bare `auth init`** — the wizard needs a TTY. Use the split flow in [`../SKILL.md`](../SKILL.md): `--site Global --no-wait`, show `verification_url` and end the turn, then `--device-code`. If the user already has Key ID / Access Key, they run `auth add` locally (do not pass secrets into the agent context).
32
30
  3. **L2 confirm is a separate chat turn** ([confirmation.md](confirmation.md)) before write ops: `device bind` / `unbind`, `group create` / rename / `delete` / `move-devices`, `device devkit create`. 「解绑这台设备」is **not** confirmation — ask (操作类型 + 环境 + EUI/组), wait for `确认`, then `--yes` where the command has it (`unbind` / `group delete` / `group move-devices`). Never pass `--yes` on the same turn as the first request.
33
31
  4. **Treat dev kit credentials as secrets** — `device_key` and `token` must not be logged or echoed unnecessarily.
34
32
  5. **Parse stdout JSON** on success; on failure read stderr and check exit code != 0.
@@ -43,7 +41,7 @@ sensecraft-cli auth info
43
41
  | State | Indicator | Action |
44
42
  |-------|-----------|--------|
45
43
  | Initialized (SenseCAP) | Output shows SenseCAP `[active]`, Key ID, Site, Organization ID | Proceed with `device` / `group` / `data` |
46
- | Not initialized | Prompts to run `auth init` | Ask the user to run `auth init` locally; for existing Access Key use `auth add` |
44
+ | Not initialized | Prints `auth init --site Global --no-wait` and says to end the turn | Run that command; show `verification_url` and stop. For an existing Access Key the user runs `auth add` |
47
45
 
48
46
  ## Configuration
49
47
 
@@ -8,8 +8,7 @@ Binary: `sensecraft-cli`. Auth: **Access Key** (`auth init`) → `{ai-host}/open
8
8
 
9
9
  ```bash
10
10
  sensecraft-cli auth info
11
- # user-only:
12
- sensecraft-cli auth init
11
+ sensecraft-cli auth init --site Global --no-wait # split flow; see SKILL.md
13
12
  ```
14
13
 
15
14
  ## Commands
@@ -12,7 +12,7 @@ Library `model download` is the published model file, not a training-job export.
12
12
  ```bash
13
13
  sensecraft-cli auth info
14
14
  ```
15
- Prefer **SenseCAP Access Key** (`auth init`) → `{ai-host}/openapi` Basic. Missing key → user runs `auth init`. **Never** run init for them.
15
+ Prefer **SenseCAP Access Key** (`auth init`) → `{ai-host}/openapi` Basic. Missing key → split `auth init` flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`.
16
16
  2. **L2 confirm is a separate chat turn** ([confirmation.md](confirmation.md)) before: `publish` / `unpublish` / `delete` / `create` / `model update` / attach-upload. 「删这个63760」is **not** confirmation — ask `将从{环境}环境删除模型 63760。删除后可能无法恢复。是否确认执行?`, wait for `确认`, then `--yes`. Never pass `--yes` on the same turn as the first request.
17
17
  3. When the user **attaches a model file** ("上传这个模型文件" / "更新模型"):
18
18
  - **Own My Models** (including already published `be_public=1`): after chat confirm, `model update --id <model_id> --path <file> --yes`. Same as Console 编辑模型. If it is **already public**, the confirm question must say 模型信息更新后将重新进入审核流程. CLI sends `be_public=1` like Console `requestConfirmFn`. JSON includes `re_review: true`.
@@ -8,9 +8,11 @@ Target binary: `sensecraft-cli` (this repo). Auth: active **SenseCAP Access Key*
8
8
 
9
9
  ```bash
10
10
  sensecraft-cli auth info
11
- sensecraft-cli auth init # user only, interactive
11
+ sensecraft-cli auth init --site Global --no-wait # split flow; see SKILL.md
12
12
  ```
13
13
 
14
+ Follow the [parent auth workflow](../SKILL.md#auth): the agent handles terminal prompts, the user completes browser authorization, then the agent rechecks auth. Do not ask the user to run CLI commands.
15
+
14
16
  ## List (existing commands)
15
17
 
16
18
  Always pass `--uniform-type 40`. Empty list → stop.
@@ -14,7 +14,7 @@ Commands: [recamera-commands.md](recamera-commands.md).
14
14
  ```bash
15
15
  sensecraft-cli auth info
16
16
  ```
17
- Need **SenseCAP Access Key** (`auth init`) for `app` / `model` / `recamera`. Never run init for them.
17
+ Need **SenseCAP Access Key** (`auth init`) for `app` / `model` / `recamera`. Missing key → split flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`.
18
18
  2. **Classic reCamera only (`40`)**. Do **not** treat Pro `53`, XIAO `32`, or Grove `36` as the same device. `/ai/recamera` redirects to Grove `36` — do not send users there.
19
19
  3. Filter **only** with API `--uniform-type 40`. Do not guess from local materials, SKU strings, or adapteds-only. Public **and** mine:
20
20
  ```bash