@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,10 +1,10 @@
1
1
  #!/usr/bin/env python3
2
- """Validate a sensecraft-app manifest (create-app skill).
2
+ """Validate a CodeCraft Hub app manifest (create-app skill).
3
3
 
4
4
  Mechanical checks only — structure, field limits, image constraints, BOM and
5
5
  block shape. This validates FORMAT, never content truth: image content,
6
- licensing, and factual accuracy remain the agent's job (see SKILL.md,
7
- Workflow A).
6
+ licensing, and factual accuracy remain the agent's job (see SKILL.md and
7
+ references/content-review.md). A pass with pending inputs is not deployability.
8
8
 
9
9
  Usage: python3 validate_manifest.py [manifest-path] [--scene-ids 1,5,...]
10
10
  (both "--scene-ids 1,5" and "--scene-ids=1,5" work; a bare or
@@ -17,30 +17,72 @@ import json
17
17
  import os
18
18
  import re
19
19
  import sys
20
+ from datetime import datetime
21
+ from urllib.parse import urlsplit
20
22
 
21
23
  IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
22
24
  IMAGE_MAX_BYTES = 5 * 1024 * 1024
23
25
  IMAGES_MAX = 16
24
26
  NAME_MAX = 60 # UTF-16 code units, Console-aligned
25
27
  EXCERPT_MAX = 300 # UTF-16 code units
26
- SCENE_RE = re.compile(r"^\d+$")
28
+ SCENE_RE = re.compile(r"^[0-9]+$")
29
+ TEXT_BLOCK_TYPES = {"step", "paragraph", "h1", "h2", "h3", "h4", "h5", "h6",
30
+ "bullet", "number", "todo", "quote", "code", "divider"}
31
+ CONFIG_TOOL_TYPES = {"deploy-ai-model", "ai-vibration", "deploy-container-app",
32
+ "node-red", "aily-blockly"}
33
+ FLASH_ADDRESSES = {"0x0", "0x4000", "0x10000", "0x90000"}
34
+ SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
35
+ QUANTITY_RE = re.compile(r"^[1-9][0-9]*$")
27
36
  # Shapes that must never appear in fields that get published. Matches
28
37
  # credential VALUES (known prefixes, key=value assignments), never the mere
29
38
  # words "token"/"password" — instructions about creating a token are legit.
30
39
  SECRET_VALUE_RE = re.compile(
31
40
  r"(mgst_[A-Za-z0-9_-]{6,}|sk-[A-Za-z0-9_-]{8,}|bearer\s+[A-Za-z0-9._-]{8,}"
32
- r"|(?i:access[_-]?key|password|passwd|secret|api[_-]?key)\s*[:=]\s*\S{6,})"
41
+ r"|(?:access[_-]?key|password|passwd|secret|api[_-]?key)\s*[:=]\s*\S{6,})",
42
+ re.IGNORECASE,
33
43
  )
34
44
  LONG_HEX_RE = re.compile(r"\b[0-9a-f]{40,}\b")
45
+ SECRET_FIELDS = {"access_key", "api_key", "password", "passwd", "secret",
46
+ "device_key", "sdk_token", "access_token", "refresh_token"}
47
+ INPUT_PLACEHOLDER_RE = re.compile(r"^(?:<[^>]+>|\$\{[^}]+\}|YOUR_[A-Z0-9_]+)$")
48
+ # Keep these aligned with rawMarkdownPatterns in internal/service/app_doc.go.
49
+ RAW_MARKDOWN_RE = re.compile(
50
+ r"\*\*[^*\n]+\*\*|__[^_\n]+__|~~[^~\n]+~~|`[^`\n]+`"
51
+ r"|^#{1,6}[ \t]|^[ \t]*[-*+][ \t]|^[ \t]*[0-9]+\.[ \t]",
52
+ re.MULTILINE,
53
+ )
35
54
 
36
55
 
37
56
  def utf16_len(s):
38
57
  return len(s.encode("utf-16-le")) // 2
39
58
 
40
59
 
60
+ def http_url(value):
61
+ if not isinstance(value, str) or any(character.isspace() for character in value):
62
+ return False
63
+ try:
64
+ parsed = urlsplit(value)
65
+ return parsed.scheme in ("http", "https") and bool(parsed.hostname)
66
+ except ValueError:
67
+ return False
68
+
69
+
70
+ def timestamp(value):
71
+ if not isinstance(value, str) or "T" not in value:
72
+ return False
73
+ try:
74
+ return datetime.fromisoformat(value.replace("Z", "+00:00")).utcoffset() is not None
75
+ except ValueError:
76
+ return False
77
+
78
+
79
+ def reject_nonfinite(_value):
80
+ raise ValueError("non-finite numbers are not valid JSON")
81
+
82
+
41
83
  def main():
42
84
  argv = sys.argv[1:]
43
- path, scene_ids = "sensecraft-app.json", set()
85
+ path, scene_ids = "codecraft-app.json", set()
44
86
  i = 0
45
87
  while i < len(argv):
46
88
  a = argv[i]
@@ -60,6 +102,11 @@ def main():
60
102
  path = a
61
103
  i += 1
62
104
 
105
+ if any(a == "--scene-ids" or a.startswith("--scene-ids=") for a in argv):
106
+ if not scene_ids or any(not SCENE_RE.fullmatch(value) for value in scene_ids):
107
+ print("ERROR: --scene-ids needs a non-empty comma-separated list of numeric ids")
108
+ return 2
109
+
63
110
  violations, warnings = [], []
64
111
 
65
112
  def vio(msg):
@@ -70,42 +117,71 @@ def main():
70
117
 
71
118
  try:
72
119
  with open(path, encoding="utf-8") as f:
73
- m = json.load(f)
74
- except (OSError, json.JSONDecodeError) as e:
120
+ m = json.load(f, parse_constant=reject_nonfinite)
121
+ except (OSError, ValueError) as e:
75
122
  print(f"VIOLATION cannot read/parse {path}: {e}")
76
123
  return 1
124
+ if not isinstance(m, dict):
125
+ print("VIOLATION manifest must be a JSON object")
126
+ return 1
77
127
  base = os.path.dirname(os.path.abspath(path))
78
128
 
79
129
  for key in ("manifest_version", "identity", "info", "images", "deployment", "bom", "sync"):
80
130
  if key not in m:
81
131
  vio(f"missing top-level section: {key}")
82
132
 
133
+ if type(m.get("manifest_version")) is not int or m["manifest_version"] != 1:
134
+ vio("manifest_version must be integer 1")
135
+ if set(m) - {"manifest_version", "identity", "info", "images", "deployment", "bom", "sync"}:
136
+ vio("unsupported top-level fields for manifest version 1")
137
+ for key in ("identity", "info", "deployment", "bom", "sync"):
138
+ if not isinstance(m.get(key), dict):
139
+ vio(f"{key} must be an object")
140
+ m[key] = {}
141
+ for key in ("be_public", "privacy"):
142
+ if key in m or key in m["info"]:
143
+ vio(f"{key} must not appear in the manifest or app info; use the parent lifecycle workflow")
144
+
83
145
  ident = m.get("identity", {})
84
146
  rt = ident.get("remote_type")
85
147
  if rt is not None and rt not in ("Global", "China", "Private"):
86
- vio(f"identity.remote_type must be Global|China|Private, got {rt!r}")
87
- if ident.get("app_id") is not None and not str(ident["app_id"]).strip():
88
- vio("identity.app_id is set but empty")
148
+ vio("identity.remote_type must be Global|China|Private or null")
149
+ app_id = ident.get("app_id")
150
+ if app_id is not None and (not isinstance(app_id, str) or not app_id.strip()):
151
+ vio("identity.app_id must be a non-empty string or null")
152
+ for key in ("org_id", "account"):
153
+ if ident.get(key) is not None and not isinstance(ident[key], str):
154
+ vio(f"identity.{key} must be a string or null")
155
+ if ident.get("created_at") is not None and not timestamp(ident["created_at"]):
156
+ vio("identity.created_at must be an RFC3339 timestamp with timezone or null")
89
157
 
90
158
  info = m.get("info", {})
159
+ if set(info) - {"app_name", "excerpt", "scene", "allow_clone", "allow_commerce", "license", "author", "activity_id"}:
160
+ vio("info contains unsupported fields; use the documented app info keys")
91
161
  name = info.get("app_name", "")
92
- if not name.strip():
93
- vio("info.app_name is empty")
162
+ if not isinstance(name, str) or not name.strip():
163
+ vio("info.app_name must be a non-empty string")
94
164
  elif utf16_len(name) > NAME_MAX:
95
165
  vio(f"info.app_name is {utf16_len(name)} UTF-16 code units (max {NAME_MAX})")
96
166
  excerpt = info.get("excerpt", "")
97
- if not excerpt.strip():
98
- vio("info.excerpt is empty")
167
+ if not isinstance(excerpt, str) or not excerpt.strip():
168
+ vio("info.excerpt must be a non-empty string")
99
169
  elif utf16_len(excerpt) > EXCERPT_MAX:
100
170
  vio(f"info.excerpt is {utf16_len(excerpt)} UTF-16 code units (max {EXCERPT_MAX})")
101
- scene = str(info.get("scene", ""))
102
- if not SCENE_RE.match(scene):
103
- vio(f"info.scene must be a string id from app_scenarios_array, got {scene!r}")
171
+ scene = info.get("scene", "")
172
+ if not isinstance(scene, str) or not SCENE_RE.fullmatch(scene):
173
+ vio("info.scene must be a numeric string id from app_scenarios_array")
104
174
  elif scene_ids and scene not in scene_ids:
105
- vio(f"info.scene {scene} not in known ids {{{', '.join(sorted(scene_ids))}}}")
175
+ vio("info.scene is not in the supplied app_scenarios_array ids")
106
176
  for flag in ("allow_clone", "allow_commerce"):
107
- if info.get(flag) not in (0, 1):
108
- vio(f"info.{flag} must be 0 or 1, got {info.get(flag)!r}")
177
+ if type(info.get(flag)) is not int or info[flag] not in (0, 1):
178
+ vio(f"info.{flag} must be integer 0 or 1")
179
+ for key in ("license", "author"):
180
+ if not isinstance(info.get(key), str):
181
+ vio(f"info.{key} must be a string (empty is allowed)")
182
+ activity_id = info.get("activity_id")
183
+ if activity_id is not None and (type(activity_id) is not int or not 0 < activity_id <= 2**63 - 1):
184
+ vio("info.activity_id must be a positive integer within the CLI's int64 range, or null/omitted for no activity")
109
185
 
110
186
  images = m.get("images", [])
111
187
  if not isinstance(images, list):
@@ -117,7 +193,13 @@ def main():
117
193
  warn("no images — fine for a private draft (omit the `images` key in the payload; the CLI rejects an empty array); a cover is required before publishing")
118
194
  if isinstance(images, list):
119
195
  for i, img in enumerate(images):
196
+ if not isinstance(img, dict):
197
+ vio(f"images[{i}] must be an object")
198
+ continue
120
199
  p, role = img.get("path", ""), img.get("role", "")
200
+ if not isinstance(p, str) or not p.strip():
201
+ vio(f"images[{i}].path must be a non-empty local path string")
202
+ continue
121
203
  if i == 0 and role != "cover":
122
204
  vio("images[0].role must be 'cover'")
123
205
  if i > 0 and role != "gallery":
@@ -134,71 +216,156 @@ def main():
134
216
  vio(f"images[{i}] {p!r}: zero-byte file")
135
217
  elif size > IMAGE_MAX_BYTES:
136
218
  vio(f"images[{i}] {p!r}: {size} bytes exceeds 5 MB")
137
- if img.get("sha256"):
138
- digest = hashlib.sha256(open(full, "rb").read()).hexdigest()
139
- if digest != img["sha256"]:
219
+ sha = img.get("sha256")
220
+ if sha is not None:
221
+ if not isinstance(sha, str) or not SHA256_RE.fullmatch(sha):
222
+ vio(f"images[{i}].sha256 must be a complete lowercase SHA-256 hex digest or null")
223
+ with open(full, "rb") as image_file:
224
+ digest = hashlib.sha256(image_file.read()).hexdigest()
225
+ if digest != sha:
140
226
  vio(f"images[{i}] {p!r}: sha256 mismatch (file changed since hash)")
141
227
  else:
142
228
  warn(f"images[{i}] {p!r}: sha256 not computed yet")
143
229
  url = img.get("file_url")
144
- if url is not None and not re.match(r"^https?://", str(url)):
145
- vio(f"images[{i}].file_url must be http(s), got {url!r}")
230
+ if url is not None and not http_url(url):
231
+ vio(f"images[{i}].file_url must be a valid http(s) URL or null")
146
232
  elif url is None:
147
233
  warn(f"images[{i}] {p!r}: not uploaded yet (file_url null)")
148
234
 
149
235
  blocks = m.get("deployment", {}).get("blocks", [])
150
236
  if not isinstance(blocks, list):
151
237
  vio("deployment.blocks must be an array")
238
+ blocks = []
152
239
  else:
240
+ if not blocks:
241
+ warn("no deployment blocks — author and review the deployment journey before claiming deployability")
153
242
  seen = set()
154
- for b in blocks:
243
+ for index, b in enumerate(blocks):
244
+ label = f"deployment.blocks[{index}]"
245
+ if not isinstance(b, dict):
246
+ vio(f"deployment.blocks[{index}]: must be an object")
247
+ continue
155
248
  bid = b.get("id")
156
- if bid in seen:
157
- vio(f"deployment.blocks: duplicate id {bid!r}")
158
- seen.add(bid)
159
- if b.get("type") == "step" and not b.get("title"):
160
- vio(f"deployment.blocks[{bid}]: step block missing title")
161
- if b.get("type") not in ("step", "paragraph", "h1", "h2", "h3", "h4", "h5", "h6",
162
- "bullet", "number", "todo", "quote", "code", "divider") \
163
- and "config" not in b:
164
- vio(f"deployment.blocks[{bid}]: tool block {b.get('type')!r} missing config")
249
+ if not isinstance(bid, str) or not bid.strip():
250
+ vio(f"deployment.blocks[{index}]: needs a non-empty string id")
251
+ elif bid in seen:
252
+ vio(f"{label}: duplicate block id")
253
+ else:
254
+ seen.add(bid)
255
+ block_type = b.get("type")
256
+ if not isinstance(block_type, str):
257
+ vio(f"{label}: type must be a supported block type string")
258
+ continue
259
+ if block_type in TEXT_BLOCK_TYPES:
260
+ if not isinstance(b.get("content"), str):
261
+ vio(f"{label}: text/code content must be a string")
262
+ elif block_type not in ("code", "divider") and RAW_MARKDOWN_RE.search(b["content"]):
263
+ vio(f"{label}: content contains raw Markdown; compile it with app doc compile before inserting tool blocks")
264
+ if block_type == "step" and (not isinstance(b.get("title"), str) or not b["title"].strip()):
265
+ vio(f"{label}: step block needs a non-empty title string")
165
266
  cfg = b.get("config")
267
+ if block_type == "flash-firmware":
268
+ if "config" in b:
269
+ vio(f"{label}: flash-firmware fields must be flat on the block, not nested in config")
270
+ cfg = b
271
+ if not b.get("device_id"):
272
+ warn(f"{label}: device_id is pending — resolve the exact device SKU")
273
+ elif not isinstance(b["device_id"], str):
274
+ vio(f"{label}: device_id must be a SKU string")
275
+ mode = b.get("flash_mode")
276
+ if mode is None or mode == "":
277
+ warn(f"{label}: flash_mode is pending")
278
+ elif mode not in ("bin", "zip"):
279
+ vio(f"{label}: flash_mode must be bin or zip")
280
+ else:
281
+ prefix = "firmware" if mode == "bin" else "project_zip"
282
+ if not b.get(prefix + "_url"):
283
+ warn(f"{label}: {prefix}_url is pending — deployment input incomplete")
284
+ for size_key in ("firmware_size", "project_zip_size"):
285
+ if size_key in b and not isinstance(b[size_key], str):
286
+ vio(f"{label}: {size_key} must be a string")
287
+ elif b.get(size_key) and not QUANTITY_RE.fullmatch(b[size_key]):
288
+ vio(f"{label}: {size_key} must be a positive byte count string or pending empty string")
289
+ address = b.get("flash_address")
290
+ if address is not None and address != "" and (not isinstance(address, str) or address not in FLASH_ADDRESSES):
291
+ vio(f"{label}: unsupported flash_address; read tool-blocks.md for device defaults")
292
+ elif block_type in CONFIG_TOOL_TYPES:
293
+ if not isinstance(cfg, dict):
294
+ vio(f"{label}: tool block {block_type!r} needs a config object")
295
+ elif block_type not in TEXT_BLOCK_TYPES:
296
+ vio(f"{label}: unsupported block type")
166
297
  if isinstance(cfg, dict):
167
298
  for k, val in cfg.items():
168
- if k.endswith("_url") and isinstance(val, str) and not val.strip():
169
- warn(f"deployment.blocks[{bid}]: config.{k} is empty — pending value, fill before publishing")
299
+ if not k.endswith("_url"):
300
+ continue
301
+ location = k if block_type == "flash-firmware" else "config." + k
302
+ if val is None or val == "":
303
+ warn(f"{label}: {location} is empty — pending deployment input")
304
+ elif not http_url(val):
305
+ vio(f"{label}: {location} must be a valid http(s) URL or a pending empty value")
170
306
 
171
307
  materials = m.get("bom", {}).get("materials", [])
172
308
  if not isinstance(materials, list):
173
309
  vio("bom.materials must be an array")
310
+ materials = []
174
311
  else:
175
312
  for i, row in enumerate(materials):
313
+ if not isinstance(row, dict):
314
+ vio(f"bom.materials[{i}] must be an object")
315
+ continue
316
+ if set(row) - {"id", "name", "quantity", "note", "buy_url", "price", "pic_url", "image"}:
317
+ vio(f"bom.materials[{i}] contains unsupported fields; project catalog sku into id rather than copying a raw catalog result")
176
318
  for forbidden in ("price", "pic_url", "image"):
177
319
  if forbidden in row:
178
320
  vio(f"bom.materials[{i}]: {forbidden!r} is not a persistable field (dropped server-side)")
179
321
  if "id" in row: # Seeed catalog row
322
+ if not isinstance(row["id"], str) or not row["id"].strip():
323
+ vio(f"bom.materials[{i}].id must be a non-empty SKU string; omit id for custom rows")
180
324
  for req in ("name", "quantity", "note", "buy_url"):
181
325
  if req not in row:
182
326
  vio(f"bom.materials[{i}] (catalog row): missing {req!r}")
183
- else: # custom row
184
- if not row.get("name") or not row.get("quantity"):
185
- vio(f"bom.materials[{i}] (custom row): needs at least name + quantity")
327
+ if not isinstance(row.get("name"), str) or not row["name"].strip():
328
+ vio(f"bom.materials[{i}].name must be a non-empty string")
329
+ if not isinstance(row.get("quantity"), str) or not QUANTITY_RE.fullmatch(row["quantity"]):
330
+ vio(f"bom.materials[{i}].quantity must be a positive integer string")
331
+ if "note" in row and not isinstance(row["note"], str):
332
+ vio(f"bom.materials[{i}].note must be a string")
333
+ if "buy_url" in row and row["buy_url"] != "" and not http_url(row["buy_url"]):
334
+ vio(f"bom.materials[{i}].buy_url must be an http(s) URL or an empty string")
186
335
 
187
336
  sync = m.get("sync", {})
188
337
  lr, lpr = sync.get("local_revision"), sync.get("last_pushed_revision")
189
- if not isinstance(lr, int) or lr < 1:
190
- vio(f"sync.local_revision must be an integer >= 1, got {lr!r}")
191
- if not isinstance(lpr, int) or lpr < 0 or (isinstance(lr, int) and lpr > lr):
192
- vio(f"sync.last_pushed_revision must be 0..local_revision, got {lpr!r}")
193
-
194
- prose_fields = [info.get("app_name", ""), info.get("excerpt", "")]
195
- prose_fields += [str(b.get("content", "")) + str(b.get("title", "")) for b in blocks if isinstance(b, dict)]
196
- prose_fields += [str(r.get("note", "")) for r in materials if isinstance(r, dict)]
197
- for text in prose_fields:
198
- if text and SECRET_VALUE_RE.search(text):
199
- vio(f"secret-shaped value in publishable text: {text[:60]!r}…")
200
- elif text and LONG_HEX_RE.search(text):
201
- warn(f"long hex literal in publishable text (key/hash?): {text[:60]!r}…")
338
+ if type(lr) is not int or lr < 1:
339
+ vio("sync.local_revision must be an integer >= 1")
340
+ if type(lpr) is not int or lpr < 0 or (type(lr) is int and lpr > lr):
341
+ vio("sync.last_pushed_revision must be 0..local_revision")
342
+ pushed_hash = sync.get("last_pushed_hash")
343
+ if pushed_hash is not None and (not isinstance(pushed_hash, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", pushed_hash)):
344
+ vio("sync.last_pushed_hash must be a full sha256:<64 lowercase hex digits> digest or null")
345
+ if sync.get("last_pushed_at") is not None and not timestamp(sync["last_pushed_at"]):
346
+ vio("sync.last_pushed_at must be an RFC3339 timestamp with timezone or null")
347
+ if type(lpr) is int and lpr > 0 and (not app_id or pushed_hash is None or sync.get("last_pushed_at") is None):
348
+ vio("a pushed revision needs app_id, last_pushed_hash, and last_pushed_at")
349
+
350
+ def check_public_values(value, location):
351
+ if isinstance(value, dict):
352
+ for key, child in value.items():
353
+ if key.lower() in SECRET_FIELDS and isinstance(child, str) and child.strip() and not INPUT_PLACEHOLDER_RE.fullmatch(child):
354
+ vio(f"{location}.{key}: credential value must not be distributed (value redacted)")
355
+ check_public_values(child, f"{location}.{key}")
356
+ elif isinstance(value, list):
357
+ for index, child in enumerate(value):
358
+ check_public_values(child, f"{location}[{index}]")
359
+ elif isinstance(value, str):
360
+ if SECRET_VALUE_RE.search(value):
361
+ vio(f"{location}: secret-shaped value in publishable data (value redacted)")
362
+ elif LONG_HEX_RE.search(value):
363
+ warn(f"{location}: long hex literal in publishable data; review whether it is a public hash")
364
+
365
+ for section in ("info", "deployment"):
366
+ check_public_values(m[section], section)
367
+ check_public_values(materials, "bom.materials")
368
+ check_public_values([img.get("file_url") for img in images if isinstance(img, dict)], "images.file_url")
202
369
 
203
370
  for w in warnings:
204
371
  print(f"WARNING {w}")
@@ -0,0 +1,55 @@
1
+ # Write and review the app for its readers
2
+
3
+ Read this before drafting any human-facing app content. Read the [field reference](../../references/app-fields.md) before filling fields and the entire [tool-block reference](../../references/tool-blocks.md) before writing deployment instructions. This guide supplements their schema and device rules; it does not replace them.
4
+
5
+ ## Give each field a purpose
6
+
7
+ | Content | Reader's question | Writing criteria |
8
+ |---|---|---|
9
+ | `app_name` | What is this app called? | Preserve its established name; propose renaming rather than adding unexplained device/marketing suffixes. Max 60 UTF-16 code units. |
10
+ | `excerpt` | Is this useful to me? | One or two clear sentences: implemented capability, audience/use case, useful outcome. Max 300 UTF-16 code units. Omit changelog, deployment sequence, framework inventory, and unsupported performance claims. Mention hardware only when it helps the reader understand the app. |
11
+ | Introduction blocks | What will I be able to do, and what should I know first? | At most two short paragraphs that add context or essential limitations. Do not repeat the excerpt verbatim or paste a developer README. |
12
+ | Step title | What action comes next? | A concrete verb/action. No manual step number; the UI supplies it. |
13
+ | Step instructions | What do I do here, and how do I know it worked? | Necessary prerequisites, actual tool/button/input, and an observable outcome. Put the relevant tool immediately after the instruction that uses it. |
14
+ | BOM note | Why do I need this part? | Its role in this app, quantity/variant clarification, and optional status where relevant. No copied catalog advertising. |
15
+
16
+ Use the user's/project's established language; ask if a consequential audience/language choice is unclear. Explain unfamiliar product-specific terms only where the reader needs them. Delete filler and superlatives whose meaning or evidence cannot be stated.
17
+
18
+ Example, assuming source evidence confirms the behavior:
19
+
20
+ - Weak excerpt: “An innovative ESP32-S3 + FOMO + Arduino project. Flash the bin and connect USB. v1.2.”
21
+ - Useful excerpt: “Count jars passing a small conveyor and view the running total on the display. Built for makers testing a simple packing-line counter.”
22
+
23
+ Do not reuse the example's claims for another project. Avoid specific accuracy, speed, compatibility, or ease-of-use promises without evidence.
24
+
25
+ ## Review the deployment as a complete journey
26
+
27
+ Before serializing blocks, outline each necessary user action with prerequisites, supported tool, verified inputs, expected result, and readiness. Choose tools because they support the project, rather than inserting every available tool type.
28
+
29
+ Start from a reader with the listed hardware and finish with the promised function running. Cover required connection/preparation, deploy/flash/install, per-user setup, first use, and stop/reset only where the project supports and needs them. Usually a few distinct actions suffice; do not force a step count or omit necessary actions to meet one.
30
+
31
+ Cross-check the plan against the real artifacts and device configuration:
32
+
33
+ - Is the exact board/variant supported by this tool and artifact? Are SKU, device type, address, architecture, and version sourced correctly?
34
+ - Can the reader carry out every action through the documented page tools and explicit preparation? Developer compilation commands are not a substitute for an available deployment tool.
35
+ - Does each required tool have usable inputs, or a documented prompt that allows the reader to supply them? A known local artifact awaiting this session's upload differs from an artifact nobody has provided.
36
+ - Are the instructions consistent with actual configuration prompts, reset behavior, and the tool's expected output? Do not invent a Wi-Fi setup screen, login flow, stop command, or success message.
37
+ - Are missing inputs visible as gaps? Empty URLs, invented IDs, placeholder containers, and instructions saying “deploy” without a functioning path do not establish a deployable app.
38
+
39
+ A needed but incomplete tool stays in the local draft. Resolve the missing input, or obtain the user's decision to save an incomplete draft and report it as such. Configuring a block does not execute it on hardware.
40
+
41
+ ## Run an editorial pass on the assembled manifest
42
+
43
+ Review the actual final values as continuous reader-facing content, including compiled text and the order of tools. This pass is separate from running the validator.
44
+
45
+ 1. **Truth:** Trace claims and compatibility statements to inspected files or user decisions. Remove roadmap features and unsupported promises. Preserve meaningful limitations.
46
+ 2. **Clarity:** Resolve vague references such as “configure it” or “click deploy” into the actual object, input, and action. Keep terms and device names consistent.
47
+ 3. **Flow:** Check prerequisites appear before use, the tool is in the right step, success can be observed, and the reader reaches the promised outcome.
48
+ 4. **Economy:** Remove repeated introductions, duplicate steps, internal development history, and spec/menu dumps. Keep enough detail to complete each action.
49
+ 5. **Presentation:** Inspect HTML/plain-text content after Markdown compilation. Check step titles, links/media, code vs prose, and accidental raw Markdown. Ensure BOM role notes and gallery order match the plan.
50
+
51
+ Fix defects before showing the final review. Record material corrections and any remaining gap in `.sensecraft/<manifest-stem>.review.md`. Preserve brief source pointers and BOM lookup evidence so a resumed session can reassess the decisions.
52
+
53
+ Present the concrete result before upload: final name/excerpt and permission choices; selected activity name/ID with dates, requirements and fit evidence, or reason for no participation; ordered steps with tool types; BOM variants/quantities and confirmation status; selected cover/assets; manifest link and remaining deployment/publishing gaps. Activity selection must follow [app-fields.md](../../references/app-fields.md#activity-selection-during-app-authoring): do not claim eligibility from a title alone or silently change permissions to qualify. Record remaining entry deliverables and distinguish selection, accepted join, verified association, and completed competition submission. The review file can carry the full copy and evidence when chat would become unwieldy. Ask only for outstanding material decisions or required authorization; do not add a ceremonial approval round for an already authorized create.
54
+
55
+ Record readiness precisely: **format validated**, **catalog verified**, **editorially reviewed**, and **deployment inputs complete** are separate findings. Include validation warnings, custom/unverified BOM rows, pending uploads versus missing artifacts, and untested hardware execution in the review. A coverless private app can have complete deployment inputs. A private app with a missing firmware URL cannot be described as ready to deploy. Run all CLI checks yourself; ask the user for unresolved decisions or required browser/device actions.