@seeed-studio/sensecraft-cli 0.4.1 → 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.
@@ -11,6 +11,8 @@ sensecraft-cli auth info
11
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
 
@@ -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
@@ -27,10 +27,11 @@ OAuth Device Flow. Obtains an Access Key and writes `sensecraft.json`.
27
27
 
28
28
  With no split flags, in a terminal:
29
29
 
30
- 1. Select site: Global (International) or China
31
- 2. Browser OAuth Device Flow authorization
32
- 3. Select an existing Access Key, or create one
33
- 4. Save to local config and set it active
30
+ 1. Select site: Global (International) or China. China supports SenseCraft Data only. SenseCraft AI and CodeCraft Hub require Global.
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.
34
35
 
35
36
  ### Split flow
36
37
 
@@ -52,7 +53,7 @@ The login access token is written to `sensecraft-auth-pending.json` next to the
52
53
 
53
54
  - Do **not** run bare `auth init` in a non-interactive shell.
54
55
  - Run the split commands above. Do not echo `access_token` or `access_key`.
55
- - In sandbox mode, simulated credentials are written locally for testing.
56
+ - In sandbox mode, simulated credentials are written locally for testing. Use an isolated test config; sandbox credentials do not authorize real cloud calls.
56
57
 
57
58
  ---
58
59
 
@@ -11,6 +11,8 @@ sensecraft-cli auth info
11
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.
@@ -2,6 +2,12 @@
2
2
 
3
3
  Help the Agent choose the right block and fill `config` safely. Execution on hardware is **L3** unless noted.
4
4
 
5
+ ## Plan before writing blocks
6
+
7
+ Read this entire reference before drafting a deployment plan or tool config. Inspect `sensecraft-cli app blocks` as the static catalog, then map the real project journey to supported actions. For each action identify prerequisites, the suitable tool, actual artifact/config sources, and the observable result. Select only tools the project needs, and place each immediately after its instructions in the flat array.
8
+
9
+ Check the exact hardware variant, artifact target/architecture, deployment inputs, and device rules below. A local file awaiting upload is a planned upload; a missing artifact or unknown target is an unresolved deployment gap. Preserve a needed tool in the local draft while resolving its inputs. Do not substitute a prose-only instruction that makes an unsupported action appear executable. Report such gaps and agree on a supported path or an explicitly incomplete draft. A format-valid block is not evidence that deployment will work.
10
+
5
11
  ## Content format
6
12
 
7
13
  The editor does **not** render Markdown on read. Preview wraps each block by `type` and treats `content` as HTML or plain text. Raw `**bold**`, `# heading`, or `- item` inside `content` shows up as those characters.
@@ -56,7 +62,7 @@ Write these as **flat fields** on the block. The editor wraps them into `config`
56
62
 
57
63
  | Field | How to write |
58
64
  |-------|----------------|
59
- | `device_id` | Material SKU string, e.g. `"100017057"`. Not a production type id (`"29"`) and not the material row `id` |
65
+ | `device_id` | Material SKU string, e.g. `"100017057"`, matching the BOM row's SKU in `id`. Not a production type (`"29"`) or an internal catalog product id |
60
66
  | `device_type` | `uniform_type` string. Use `""` when the board has none (Wio / Grove may) |
61
67
  | `flash_mode` | `"bin"` when a firmware URL is set. `"zip"` for a project zip |
62
68
  | `firmware_url` / `firmware_name` / `firmware_size` | Bin mode. `firmware_size` is a string, not a number. Empty `firmware_name` is filled from the URL by the editor |