@akinet/akidevrule 3.0.0

package/skills/aki-article-writer/references/article-workflow.md

@@ -0,0 +1,377 @@
+# aki-article-writer — Full Six-Phase Pipeline
+
+This document is the complete operating procedure for the **Article Worker subagent**.
+The Article Worker reads this file in full before beginning any work.
+
+---
+
+## Phase 1 — Research & Fact-Verification
+
+**Goal:** Collect verified information. Zero hallucination.
+
+### 1.1 Source collection
+
+Use `search_web` to gather information from at least **two independent authoritative sources** for every major claim. Authority by project domain:
+
+| Domain | Authoritative sources |
+|---|---|
+| `kinhdich` / `tuvi` | Classical texts (I Ching, Tử Vi Bình Chú), recognised scholars with wide citations |
+| `vstshop` | Manufacturer website, official release notes (FabFilter, Spectrasonics, Native Instruments…) |
+| `akinet` / `akitao` | Official API docs, RFC, vendor technical documentation |
+| General | Wikipedia (as a pointer to primary sources, not the source itself), reputable publications |
+
+### 1.2 Claim classification
+
+Label every load-bearing statement before writing:
+
+| Tag | Meaning | Requirement |
+|---|---|---|
+| `FACT` | Verified across 2+ independent sources | Cite sources inline in draft notes |
+| `ANALYSIS` | Author's reasoned interpretation | Signal in text: "Có thể thấy rằng…" / "According to this reading…" |
+| `UNVERIFIED` | Cannot be confirmed right now | **Do not include in the published article** |
+
+A mislabelled FACT that is actually an ASSUMPTION is the one unrecoverable error in this phase.
+
+### 1.3 File vs chat separation
+
+Article content must be context-independent and durable. Do not copy conversation wording, task-specific shorthand, or ephemeral discussion into the published file.
+
+---
+
+## Phase 2 — Metadata & JSON-LD Schema
+
+**Execute before writing body content.** Everything downstream inherits the terminology and framing defined here.
+
+### 2.1 Slug
+
+```
+Format: lowercase, hyphen-separated, no diacritics
+Example: giai-ma-que-thuan-can
+```
+
+### 2.2 Meta title
+
+- ≤ 60 characters total (articles/knowledge/post slug pages: ≤ 80 chars)
+- **Do NOT include the brand name** — the framework appends ` | BrandName` automatically; including it produces a double suffix
+- Focus keyphrase at the start
+- No em-dash (`—`) or en-dash (`–`) — use `|` or `-` instead
+- Define once as a `const`; pass the same variable to OG, Twitter card, and JSON-LD — never repeat the literal string
+
+### 2.3 Meta description
+
+- ≤ 155 characters
+- Structure: `[Action verb] + [Focus keyphrase] + [User benefit]`
+- Example: "Khám phá quẻ Thuần Càn trong Kinh Dịch — ý nghĩa 6 hào, ứng dụng phong thủy và bài học lãnh đạo đích thực."
+
+### 2.4 JSON-LD schema — type matrix
+
+Select the correct schema type based on project:
+
+| Content type | Required schemas | Key fields |
+|---|---|---|
+| Blog / news | `BlogPosting` + `Person` + `Organization` + `BreadcrumbList` | `headline`, `author`, `publisher`, `datePublished`, `image` |
+| Knowledge / glossary (kinhdich, tuvi) | `Article` + `DefinedTerm` + `DefinedTermSet` + `BreadcrumbList` | `definedTermCode`, `inDefinedTermSet` |
+| Product (vstshop) | `Product` + `Organization` + `Offer` + `BreadcrumbList` | `price`, `priceCurrency`, `availability` |
+| Service / feature | `Service` + `Organization` + `BreadcrumbList` | `serviceType`, `provider` |
+
+**Organization block — required on every page:**
+
+```json
+{
+  "@type": "Organization",
+  "name": "BrandName",
+  "alternateName": ["Brand Name", "brandname", "brandname.com"],
+  "url": "https://domain.com/",
+  "logo": "https://domain.com/favicon/icon-192.png",
+  "sameAs": ["https://facebook.com/...", "https://wikidata.org/..."],
+  "knowsAbout": ["Topic 1", "Topic 2"]
+}
+```
+
+> **FAQPage schema (2026 note):** Google retired FAQ rich results in May 2026. Do not write an FAQ block solely to emit schema. Instead, write H2s phrased as questions — AI crawlers (Perplexity, ChatGPT, Gemini) cite paragraphs following question-phrased H2s at roughly double the rate of JSON-LD FAQPage entries. Existing FAQPage markup may be kept (it causes no harm), but never create it as a new SEO deliverable.
+
+### 2.5 URL canonical & trailing slash
+
+All canonical URLs, sitemap entries, `og:url`, internal links, and JSON-LD `url` fields must end with `/`. Required for Cloudflare Pages compatibility.
+
+---
+
+## Phase 3 — Content Writing & UX Psychology
+
+### 3.1 Heading structure
+
+```
+H1 — exactly one per article; contains the focus keyphrase
+  H2 — 3–5 main sections
+    H3 — sub-detail within an H2 (only when genuinely needed)
+```
+
+Write at least one H2 as a direct question (ending with `?`). AI crawlers are roughly twice as likely to cite a passage when it follows a question-shaped heading.
+
+### 3.2 Cognitive budget — opening sentences
+
+Users scan web content; they do not read linearly. Every paragraph opening and every FAQ answer must lead with the core answer in the first sentence (Subject + Verb + Predicate). No warm-up.
+
+**Banned openers:**
+- "Đây là…" / "This is…"
+- "Trong bài viết này…" / "In this article…"
+- "Theo như chúng ta đã biết…" / "As we all know…"
+- "According to…" at the start of a paragraph
+
+**Paragraph length:** ≤ 5 lines. If longer, split or convert to a list.
+
+Example:
+```
+❌  "Trong phần này, chúng ta sẽ cùng tìm hiểu về những ứng dụng thú vị…"
+✅  "Quẻ Thuần Càn chỉ dẫn 3 nguyên tắc lãnh đạo: kiên trì, thuận thời và học hỏi không ngừng."
+```
+
+### 3.3 Semantic stability
+
+Use exactly one canonical term for each concept throughout the article. Synonym variation may seem stylistically rich but confuses both readers and AI crawlers. Pick the term, define it once, use it consistently.
+
+### 3.4 Vietnamese dual-coverage (vi locale)
+
+Google treats `vst là gì` and `vst la gi` as different queries. To cover both without degrading readability:
+
+- Embed the unaccented form in parentheses at its **first occurrence** in body copy or FAQ: `…VST (vst la gi) là loại phần mềm…`
+- Or place it in `keywords` meta or `alternateName` in schema
+
+**Never** place unaccented forms in H1, H2, H3, or FAQ question text — it degrades the visual quality of the interface.
+
+### 3.5 Anxiety handling at CTA
+
+At every call-to-action point (sign-up, purchase, download, consult), identify the dominant user anxiety at that moment and answer it right there — not on a distant FAQ page:
+
+| Anxiety | Answer at the CTA |
+|---|---|
+| Price / lock-in | "Dùng thử miễn phí 14 ngày, không cần thẻ tín dụng" |
+| Complexity | "Tư vấn 1-1 miễn phí trong 15 phút" |
+| Compatibility | "Hỗ trợ Win/Mac, tương thích mọi DAW phổ biến" |
+| Privacy | "Không lưu dữ liệu cá nhân, xoá tài khoản bất cứ lúc nào" |
+
+### 3.6 Internal & external links
+
+- **Internal links:** ≥ 2 links to related articles or service pages within the same project
+- **External links:** link to authoritative sources when citing data; add `rel="noopener"`
+
+### 3.7 SSR / prerender requirement
+
+69% of AI crawlers (ChatGPT, ClaudeBot, PerplexityBot, OAI-SearchBot) do not execute JavaScript. All article content, meta tags, and schema must be present in the server-rendered HTML at crawl time — never client-side only.
+
+---
+
+## Phase 4 — Image Scout Pipeline
+
+Spawn a separate **Image Scout subagent** with model Gemini Flash or Claude Haiku.
+
+### Step 0 — Resolve `article_arch` before spawning
+
+Check the render path, not just `CLAUDE.md` prose: open the component/template that actually renders an article body (e.g. `ContentArticle.vue`, an MDX renderer, a markdown-to-HTML pipeline) and confirm whether it parses inline markdown image syntax `![]()` inside body content.
+
+- **Renderer parses `![]()` or reads a per-block `image` field → `article_arch: markdown`.** Multiple images (hero + N body) are safe. Proceed with `count_needed: <1 hero + N body images>` as before.
+- **Renderer does NOT parse `![]()`** (e.g. a hand-written `renderMarkdown()` that only handles bold/link/code, with no image field in the content schema) **→ `article_arch: component`, single-image mode.** `count_needed` is forced to **1**. Do not generate body images the renderer cannot display — they would ship as literal, broken `![alt](path)` text.
+
+**Brief to pass:**
+```
+{
+  "slug": "<article-slug>",
+  "topic": "<article topic in plain language>",
+  "article_arch": "markdown" | "component",
+  "count_needed": <1 hero + N body images, or exactly 1 if article_arch is "component">,
+  "output_dir": "<project image directory, e.g. public/images/articles/>",
+  "format": "webp"   // or "jpg" per project config
+}
+```
+
+The Image Scout executes the following seven steps:
+
+### Step 1 — Search (`search_web`)
+
+```
+Query patterns:
+  "<topic> cover art official high resolution"
+  "<topic> image 16:9 landscape"
+  "<product name> <brand> official product image square"
+
+Preferred sources:
+  Manufacturer / official rights-holder website
+  Unsplash, Pexels (CC0 / royalty-free)
+  Wikimedia Commons
+
+Disqualified sources:
+  Images bearing a third-party watermark
+  Images showing a competitor's logo or branding
+  Images with visible text unrelated to the topic
+```
+
+Collect 3–5 candidate image URLs.
+
+### Step 2 — Download (`curl`)
+
+```bash
+curl -sSL \
+  -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
+  "<IMAGE_URL>" \
+  -o /tmp/raw-<slug>-<index>.jpg
+```
+
+The browser User-Agent string is required — many CDNs block requests without it.
+
+### Step 3 — Visual inspection before processing (`view_file`)
+
+**Mandatory:** call `view_file` on `/tmp/raw-<slug>-<index>.jpg` for every candidate.
+
+Reject if any of the following is true:
+- [ ] Wrong subject / wrong product version
+- [ ] Blurry, pixelated, or heavily compression-artefacted
+- [ ] Visible third-party watermark
+- [ ] Competitor logo or branding visible
+- [ ] Key content is not centred (will be lost in square or 16:9 crop)
+
+If a candidate fails → go back to Step 1 and find a replacement URL.
+
+### Step 4 — File naming (slug convention)
+
+```
+Multi-image mode (article_arch: markdown):
+  Pattern:  <article-slug>-<zero-padded-index>.<ext>
+  Hero:     giai-ma-que-thuan-can-01.webp
+  Body 1:   giai-ma-que-thuan-can-02.webp
+  Body 2:   giai-ma-que-thuan-can-03.webp
+
+Single-image mode (article_arch: component, count_needed: 1):
+  Pattern:  <article-slug>.<ext>
+  File:     giai-ma-que-thuan-can.webp
+```
+
+Single-image mode always writes to `public/images/articles/<slug>.<ext>` regardless of the project's `image_dir` fallback default — this is the one path the record's `ogImage`/share-image field and the rendered hero both point to (see Phase 5).
+
+### Step 5 — Processing (`ffmpeg` / `sips`)
+
+**Option A — `ffmpeg` (recommended, most accurate):**
+
+```bash
+# Hero / OG image — 1200×630 px, 16:9 center crop
+ffmpeg -i /tmp/raw-<slug>-01.jpg \
+  -vf "crop='min(iw,ih*16/9)':'min(ih,iw*9/16)',scale=1200:630:flags=lanczos" \
+  -q:v 2 <output_dir>/<slug>-01.webp -y
+
+# Body image — 800 px width, original ratio preserved
+ffmpeg -i /tmp/raw-<slug>-02.jpg \
+  -vf "scale=800:-1:flags=lanczos" \
+  -q:v 80 <output_dir>/<slug>-02.webp -y
+
+# Square product image — 800×800 px, center crop (for vstshop-style)
+ffmpeg -i /tmp/raw-<slug>-01.jpg \
+  -vf "crop='min(iw,ih)':'min(iw,ih)',scale=800:800:flags=lanczos" \
+  -q:v 2 <output_dir>/<slug>-01.webp -y
+```
+
+**Option B — `sips` (macOS native fallback):**
+
+```bash
+# Resize to 1200 px wide first
+sips --resampleWidth 1200 /tmp/raw-<slug>-01.jpg --out /tmp/resized-<slug>-01.jpg
+# Crop 1200×630 from centre
+sips --cropToHeightWidth 630 1200 /tmp/resized-<slug>-01.jpg --out <output_dir>/<slug>-01.jpg
+```
+
+**Size and weight targets:**
+
+| Image role | Dimensions | Max file size |
+|---|---|---|
+| Hero / OG (16:9) | 1200 × 630 px | < 150 KB |
+| Square product cover | 800 × 800 px | < 120 KB |
+| Body / inline | Width 800 px | < 90 KB |
+
+### Step 6 — Visual inspection after processing (`view_file`)
+
+**Mandatory:** call `view_file` on the output file.
+
+Confirm:
+- [ ] File opens and displays correctly (not corrupt)
+- [ ] Correct dimensions (width and height match spec)
+- [ ] No important content clipped by the crop
+- [ ] Acceptable visual quality
+
+### Step 7 — Cleanup and handoff
+
+```bash
+rm /tmp/raw-<slug>-*.jpg /tmp/resized-<slug>-*.jpg 2>/dev/null
+```
+
+Return structured result to Article Worker:
+```
+hero:  { file: "<slug>-01.webp", alt: "<SEO alt text containing focus keyphrase>" }
+body:  [
+  { file: "<slug>-02.webp", alt: "..." },
+  { file: "<slug>-03.webp", alt: "..." }
+]
+```
+
+---
+
+## Phase 5 — Image Embed
+
+Article Worker receives the Image Scout's result. Embed method depends on `article_arch` resolved in Phase 4 Step 0 — never default to markdown syntax without checking.
+
+**Alt text rules (both paths):**
+- Must contain the focus keyphrase
+- Must accurately describe the image content (no keyword stuffing)
+- ≤ 125 characters
+
+### `article_arch: markdown`
+
+Embed with markdown image syntax directly in body content:
+```markdown
+![Giải mã quẻ Thuần Càn trong Kinh Dịch — ý nghĩa và ứng dụng](/images/articles/giai-ma-que-thuan-can-01.webp)
+```
+
+### `article_arch: component` (single-image mode)
+
+Do **not** write `![]()` anywhere in body/paragraph fields — the renderer does not parse it and will print the literal text. Instead:
+1. Set the content record's existing share-image field (e.g. `ogImage`) to `/images/articles/<slug>.<ext>`.
+2. Confirm the shared render component (e.g. `ContentArticle.vue`) already displays that field as a hero image above the body. If it does not yet, that is a one-time component change to flag to the user — do not route around it with markdown text in a paragraph.
+3. No separate body images in this mode; one image serves as both hero and OG/share image.
+
+---
+
+## Phase 6 — Self-Audit & Delivery
+
+Article Worker runs through the full checklist before reporting completion.
+
+### 6.1 Meta & technical SEO
+- [ ] Meta title ≤ 60 chars (≤ 80 for article/knowledge slug pages)
+- [ ] Meta title: no brand suffix, no em-dash, no en-dash
+- [ ] Meta description ≤ 155 chars, starts with an action verb
+- [ ] Canonical URL and all internal links end with `/`
+- [ ] Exactly one H1
+- [ ] JSON-LD valid; Organization block has `alternateName`, `knowsAbout`, `sameAs`
+- [ ] Focus keyphrase appears in: H1, Meta title, Meta description, first paragraph opening, ≥ 1 H2
+
+### 6.2 Content quality
+- [ ] No `UNVERIFIED` claim appears in the published text
+- [ ] No banned openers in any paragraph or FAQ answer
+- [ ] No paragraph exceeds 5 lines
+- [ ] Unaccented Vietnamese keyword embedded in parentheses at first occurrence in body / FAQ (vi locale only)
+- [ ] CTA point has an anxiety-answering line
+- [ ] ≥ 1 H2 is a direct question (ends with `?`)
+- [ ] ≥ 2 internal links
+- [ ] External links carry `rel="noopener"`
+
+### 6.3 Image
+- [ ] Hero image exists at the correct path, correct dimensions, visually sharp
+- [ ] `article_arch` was resolved from the actual renderer, not assumed
+- [ ] If `markdown`: all body images exist, correct spec, filenames follow slug-index convention (`<slug>-01.webp`, etc.), every `![]()` has a focus-keyphrase alt text ≤ 125 chars
+- [ ] If `component` (single-image mode): exactly one image at `public/images/articles/<slug>.<ext>`, no `![]()` written into any body/paragraph field, the record's `ogImage`/share-image field points to that same file
+- [ ] `/tmp/` scratch files removed
+
+### 6.4 SSR / prerender
+- [ ] Article content, meta tags, and schema are present in server-rendered HTML, not deferred to client-side JS
+
+---
+
+## Antigravity / AGY note
+
+AGY has no native subagent spawn mechanism. When running under AGY (CLI or IDE), execute phases 1–6 sequentially in a single session. For Phase 4, open the Image Scout as a separate AGY conversation and paste its output back into the main session. This trades true isolation for sequential clarity — the content quality rules are unchanged.

package/skills/akidevsync-notes/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: akidevsync-notes
+description: Read and edit a project's `.akidevsync/notes.json` task/note file — the per-project task list written by the Aki-Dev-Sync app (github.com/lacvietanh/aki-dev-sync). Use when the user asks to list, add, pin/unpin, mark done, edit, or delete a task in that file, or mentions "task note", "note ghim", "pin task", "mark done", "notes.json", "akidevsync task". Also use when asked to cross-check pinned/open notes against what a release actually shipped (CHANGELOG, code) before marking them done.
+---
+
+# akidevsync-notes — edit a project's Aki-Dev-Sync task file safely
+
+The Aki-Dev-Sync app stores every project's task list at `<project>/.akidevsync/notes.json` (schema: `about`, `schema`, `notes`, `tasks[]`, `updated_at`; each task has `id`, `title`, `detail`, `done`, `pin`, `wish`, `created_at`, `updated_at` in epoch-ms). The file is normally gitignored (`.akidevsync/` — the app excludes it from PUSH/PULL by default too), so edits here are local-only and never show up in `git diff`.
+
+**Never hand-edit the JSON with the Edit tool.** The app itself reads/writes this file, so any mutation must match its exact formatting (2-space indent, `ensure_ascii=False` so Vietnamese text stays literal, alphabetical per-task key order, a trailing newline) or the next diff a human looks at gets noisy for no reason. Always go through the bundled script:
+
+```
+python3 ~/.claude/skills/akidevsync-notes/scripts/notes_cli.py <path-to-notes.json> <command> [args]
+```
+
+(On Antigravity/Codex/Kiro/Grok, substitute that CLI's skills root — see `~/.aki/akidevrule/.source-repo`'s `README.md` for the list of sync targets.)
+
+## Locating the file
+
+`find <project-root> -maxdepth 2 -name notes.json -path '*/.akidevsync/*'` (or just check `<cwd>/.akidevsync/notes.json`). If it does not exist, the project has never opened in Aki-Dev-Sync, or task notes were never migrated — **do not create one uninvited**. Only run `... init` when the user explicitly asks to start tracking tasks for a project that doesn't use the app.
+
+## Commands
+
+```
+list [--pin] [--done] [--pending] [--wish] [--detail]   # --detail also prints each task's detail body
+add "<title>" [--detail "<text>"] [--pin] [--wish]
+set <task-id> [--done true|false] [--pin true|false] [--wish true|false] [--title "<t>"] [--detail "<t>"]
+delete <task-id>                                          # permanent — confirm with the user first
+note "<text>"                                              # replaces the project-wide notes field (not a task)
+init                                                        # only if the user explicitly wants a new file
+```
+
+`set`/`delete` need the task's `id` (shown by `list`) — never guess it from the title, titles are not unique.
+
+## Cross-checking pinned notes against a shipped release
+
+A recurring use: the user pins a wish/bug note while working, ships a release, then asks "does what I fixed in vX.Y actually cover this note — mark it done." Work like this, not by pattern-matching titles alone:
+
+1. `list --pin` (or `list --pending` for everything still open) to get the candidate set.
+2. For each note, read its `detail` too — the real bug report is usually there, not in the short title, and is often the most reliable string to grep the CHANGELOG for.
+3. Read the actual CHANGELOG entry (or `git log`) for the release, and where the claim is non-trivial, verify against the code itself (grep the relevant file/function) rather than trusting the changelog prose alone — changelog text can overstate what shipped.
+4. If the changelog or code itself flags the fix as unverified/runtime-only/needs-owner-confirmation, **ask the user** whether they've actually confirmed it before marking done — do not mark done on an unverified claim just because the code changed.
+5. Only `set <id> --done true` for notes you can point to a specific matching commit/changelog line/code diff for. Leave ambiguous or unmatched ones pinned and tell the user why, rather than silently leaving them out of the report.
+6. Summarize what you marked done and why (one line per note, citing the matching change) so the user can sanity-check the batch rather than re-deriving it.
+
+## What this skill does not do
+
+It has no opinion on the app's UI, sync, or release process — it only edits `notes.json`. Never touch other files in `.akidevsync/`, never run git commands on this path (it's meant to stay untracked), and never bulk-delete tasks without the user naming them explicitly.

package/skills/akidevsync-notes/scripts/notes_cli.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""CLI for reading/mutating an Aki-Dev-Sync `.akidevsync/notes.json` task file.
+
+Schema (as written by the Aki-Dev-Sync app itself):
+  { "about": "<url>", "schema": 1, "notes": "<free text>",
+    "tasks": [ { "id", "title", "detail", "done", "pin", "wish",
+                 "created_at", "updated_at" } (ms epoch ints) ],
+    "updated_at": <ms epoch int> }
+
+Every mutation preserves the on-disk key order (alphabetical per task,
+declared order at root) so a diff against the app's own next write stays
+quiet, and writes back with ensure_ascii=False (Vietnamese text unescaped)
+and a trailing newline, matching the app's own formatting.
+"""
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+TASK_KEY_ORDER = ["created_at", "detail", "done", "id", "pin", "title", "updated_at", "wish"]
+ROOT_KEY_ORDER = ["about", "schema", "notes", "tasks", "updated_at"]
+
+
+def now_ms():
+    return int(time.time() * 1000)
+
+
+def load(path):
+    p = Path(path)
+    if not p.exists():
+        sys.exit(f"error: {path} does not exist (this project has no Aki-Dev-Sync task notes yet)")
+    with p.open(encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save(path, data):
+    data["updated_at"] = now_ms()
+    with Path(path).open("w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+
+
+def new_id(data):
+    existing = {t["id"] for t in data["tasks"]}
+    ts = now_ms()
+    tid = f"task-{ts}"
+    while tid in existing:
+        ts += 1
+        tid = f"task-{ts}"
+    return tid, ts
+
+
+def ordered_task(fields):
+    return {k: fields[k] for k in TASK_KEY_ORDER}
+
+
+def find_task(data, task_id):
+    for t in data["tasks"]:
+        if t["id"] == task_id:
+            return t
+    sys.exit(f"error: no task with id {task_id!r}")
+
+
+def cmd_list(args):
+    data = load(args.path)
+    tasks = data["tasks"]
+    if args.pin:
+        tasks = [t for t in tasks if t["pin"]]
+    if args.pending:
+        tasks = [t for t in tasks if not t["done"]]
+    if args.done:
+        tasks = [t for t in tasks if t["done"]]
+    if args.wish:
+        tasks = [t for t in tasks if t["wish"]]
+    for t in tasks:
+        mark = "x" if t["done"] else " "
+        pin = "📌" if t["pin"] else "  "
+        print(f"[{mark}] {pin} {t['id']}  {t['title']}")
+        if args.detail and t["detail"]:
+            for line in t["detail"].splitlines():
+                print(f"        {line}")
+
+
+def cmd_add(args):
+    data = load(args.path)
+    tid, ts = new_id(data)
+    task = ordered_task({
+        "created_at": ts,
+        "detail": args.detail or "",
+        "done": False,
+        "id": tid,
+        "pin": bool(args.pin),
+        "title": args.title,
+        "updated_at": ts,
+        "wish": bool(args.wish),
+    })
+    data["tasks"].append(task)
+    save(args.path, data)
+    print(json.dumps(task, ensure_ascii=False, indent=2))
+
+
+def cmd_set(args):
+    data = load(args.path)
+    t = find_task(data, args.task_id)
+    changed = False
+    if args.done is not None:
+        t["done"] = args.done
+        changed = True
+    if args.pin is not None:
+        t["pin"] = args.pin
+        changed = True
+    if args.wish is not None:
+        t["wish"] = args.wish
+        changed = True
+    if args.title is not None:
+        t["title"] = args.title
+        changed = True
+    if args.detail is not None:
+        t["detail"] = args.detail
+        changed = True
+    if not changed:
+        sys.exit("error: set needs at least one of --done/--pin/--wish/--title/--detail")
+    t["updated_at"] = now_ms()
+    save(args.path, data)
+    print(json.dumps(t, ensure_ascii=False, indent=2))
+
+
+def cmd_delete(args):
+    data = load(args.path)
+    before = len(data["tasks"])
+    data["tasks"] = [t for t in data["tasks"] if t["id"] != args.task_id]
+    if len(data["tasks"]) == before:
+        sys.exit(f"error: no task with id {args.task_id!r}")
+    save(args.path, data)
+    print(f"deleted {args.task_id}")
+
+
+def cmd_note(args):
+    data = load(args.path)
+    data["notes"] = args.text
+    save(args.path, data)
+    print("notes field updated")
+
+
+def cmd_init(args):
+    p = Path(args.path)
+    if p.exists():
+        sys.exit(f"error: {args.path} already exists — refusing to overwrite")
+    p.parent.mkdir(parents=True, exist_ok=True)
+    data = {k: v for k, v in {
+        "about": "https://github.com/lacvietanh/aki-dev-sync",
+        "schema": 1,
+        "notes": "",
+        "tasks": [],
+        "updated_at": now_ms(),
+    }.items()}
+    data = {k: data[k] for k in ROOT_KEY_ORDER}
+    save(args.path, data)
+    print(f"created {args.path}")
+
+
+def parse_bool(s):
+    return s.lower() in ("1", "true", "yes", "on")
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("path", help="path to .akidevsync/notes.json")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_list = sub.add_parser("list", help="list tasks")
+    p_list.add_argument("--pin", action="store_true", help="only pinned tasks")
+    p_list.add_argument("--done", action="store_true", help="only done tasks")
+    p_list.add_argument("--pending", action="store_true", help="only not-done tasks")
+    p_list.add_argument("--wish", action="store_true", help="only wishlist tasks")
+    p_list.add_argument("--detail", action="store_true", help="also print each task's detail")
+    p_list.set_defaults(func=cmd_list)
+
+    p_add = sub.add_parser("add", help="add a new task")
+    p_add.add_argument("title")
+    p_add.add_argument("--detail", default="")
+    p_add.add_argument("--pin", action="store_true")
+    p_add.add_argument("--wish", action="store_true")
+    p_add.set_defaults(func=cmd_add)
+
+    p_set = sub.add_parser("set", help="update fields on an existing task")
+    p_set.add_argument("task_id")
+    p_set.add_argument("--done", type=parse_bool, default=None)
+    p_set.add_argument("--pin", type=parse_bool, default=None)
+    p_set.add_argument("--wish", type=parse_bool, default=None)
+    p_set.add_argument("--title", default=None)
+    p_set.add_argument("--detail", default=None)
+    p_set.set_defaults(func=cmd_set)
+
+    p_del = sub.add_parser("delete", help="remove a task permanently")
+    p_del.add_argument("task_id")
+    p_del.set_defaults(func=cmd_delete)
+
+    p_note = sub.add_parser("note", help="replace the project-wide notes text")
+    p_note.add_argument("text")
+    p_note.set_defaults(func=cmd_note)
+
+    p_init = sub.add_parser("init", help="create a new empty notes.json (only if missing)")
+    p_init.set_defaults(func=cmd_init)
+
+    args = ap.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()