annotask 0.0.5 → 0.0.6

package/README.md

@@ -169,6 +169,13 @@ Start your dev server, then open:
 - **Violation cards** — Shows impact level, rule, description, and affected element count
 - **One-click fix tasks** — Create tasks from violations with full context (HTML snippets, CSS selectors, source file/line, and fix suggestions)
 
+### Screenshots
+- **Snipping tool** — Click "Add Screenshot" on any task form, then drag a region or click for full-page capture
+- **Thumbnail preview** — Screenshot appears as a preview on the task form before submitting (removable)
+- **Task-attached** — Screenshots are stored on the server and referenced by filename in the task
+- **Multimodal AI context** — AI agents can download and view screenshots for visual understanding of what the user sees
+- **Auto-cleanup** — Screenshot files are deleted when the task is accepted
+
 ### AI agent context
 - **Interaction history** — Optionally track user navigation and button/link clicks in the app so the AI agent understands how the user reached the current state
 - **Element context** — Optionally capture ancestor layout chain (3 levels of parent display, flex-direction, gap, grid-template) and DOM subtree (3 levels of children with tag, classes, text) for each task
@@ -186,10 +193,11 @@ Start your dev server, then open:
 annotask watch              # Live stream of changes
 annotask report             # Fetch current report JSON
 annotask status             # Check connection
+annotask screenshot <id>    # Download a task's screenshot
 annotask init-skills        # Install agent skills into your project
 ```
 
-Options: `--port=N`, `--host=H`, `--server=URL` (override server.json), `--mfe=NAME` (filter by MFE).
+Options: `--port=N`, `--host=H`, `--server=URL` (override server.json), `--mfe=NAME` (filter by MFE), `--output=PATH` (for screenshot command).
 
 ## API
 
@@ -197,6 +205,8 @@ Options: `--port=N`, `--host=H`, `--server=URL` (override server.json), `--mfe=N
 - `GET /__annotask/api/tasks` — Task list (supports `?mfe=NAME` filter)
 - `POST /__annotask/api/tasks` — Create a task
 - `PATCH /__annotask/api/tasks/:id` — Update task status
+- `POST /__annotask/api/screenshots` — Upload a screenshot (base64 PNG)
+- `GET /__annotask/screenshots/:filename` — Serve a screenshot
 - `GET /__annotask/api/status` — Health check
 - `ws://localhost:5173/__annotask/ws` — Live WebSocket stream
 

package/dist/cli.js

@@ -48,6 +48,10 @@ if (command === "watch") {
   initSkills();
 } else if (command === "screenshot") {
   fetchScreenshot();
+} else if (command === "tasks") {
+  fetchTasks();
+} else if (command === "update-task") {
+  updateTask();
 } else if (command === "help" || command === "--help") {
   printHelp();
 } else {
@@ -189,6 +193,45 @@ async function fetchScreenshot() {
     process.exit(1);
   }
 }
+async function fetchTasks() {
+  try {
+    const tasksUrl = mfeFilter ? `${apiUrl}/tasks?mfe=${encodeURIComponent(mfeFilter)}` : `${apiUrl}/tasks`;
+    const res = await fetch(tasksUrl);
+    const data = await res.json();
+    console.log(JSON.stringify(data, null, 2));
+  } catch (err) {
+    console.error(`\x1B[31m[Annotask]\x1B[0m Failed to fetch tasks: ${err.message}`);
+    process.exit(1);
+  }
+}
+async function updateTask() {
+  const taskId = args[1];
+  const statusArg = args.find((a) => a.startsWith("--status="))?.split("=")[1];
+  const feedbackArg = args.find((a) => a.startsWith("--feedback="))?.split("=")[1];
+  if (!taskId || !statusArg) {
+    console.error("\x1B[31m[Annotask]\x1B[0m Usage: annotask update-task <task-id> --status=<status> [--feedback=<text>]");
+    console.error("  Valid statuses: pending, applied, review, accepted, denied");
+    process.exit(1);
+  }
+  try {
+    const body = { status: statusArg };
+    if (feedbackArg) body.feedback = feedbackArg;
+    const res = await fetch(`${apiUrl}/tasks/${taskId}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    const data = await res.json();
+    if (data.error) {
+      console.error(`\x1B[31m[Annotask]\x1B[0m ${data.error}`);
+      process.exit(1);
+    }
+    console.log(JSON.stringify(data, null, 2));
+  } catch (err) {
+    console.error(`\x1B[31m[Annotask]\x1B[0m Failed to update task: ${err.message}`);
+    process.exit(1);
+  }
+}
 function initSkills() {
   const __dirname = dirname(fileURLToPath(import.meta.url));
   const srcSkills = resolve(__dirname, "..", "skills");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "annotask",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "license": "MIT",
   "type": "module",
   "module": "./dist/index.js",

package/skills/annotask-apply/SKILL.md

@@ -16,37 +16,18 @@ Annotask is a visual markup tool that integrates with Vite and Webpack. The user
 
 ## Steps
 
-### 0. Discover server URL
-
-Read `.annotask/server.json` in the **current working directory only** (never search parent directories):
-
-```bash
-cat .annotask/server.json
-```
-
-This returns `{ "url": "http://localhost:PORT", "port": PORT }`. Use the `url` value as `BASE_URL` for all API calls below.
-
-If the file contains a `"mfe"` field (e.g. `"mfe": "@myorg/my-mfe"`), this project is a **micro-frontend** and the server is running on a remote root shell. Save the `mfe` value as `MFE_FILTER` — you will use it to filter tasks in step 1.
-
-If the file does not exist, probe for a running server:
+### 0. Check server status
 
 ```bash
-curl -s http://localhost:24678/__annotask/api/status
-curl -s http://localhost:5173/__annotask/api/status
+annotask status
 ```
 
-Use whichever responds with `{"status":"ok"}`. **IMPORTANT: Do NOT read server.json from parent or sibling directories — it belongs to a different project.**
+If this fails, the Annotask dev server isn't running. Ask the user to start it.
 
 ### 1. Fetch pending tasks
 
-If `MFE_FILTER` is set (from step 0), append it as a query parameter to filter tasks for this project:
-
 ```bash
-# Without MFE filter (standard single-project setup):
-curl -s $BASE_URL/__annotask/api/tasks
-
-# With MFE filter (micro-frontend setup):
-curl -s $BASE_URL/__annotask/api/tasks?mfe=$MFE_FILTER
+annotask tasks
 ```
 
 Response:
@@ -62,13 +43,24 @@ Response:
       "file": "src/components/Header.vue",
       "line": 5,
       "action": "text_edit",
-      "context": { "element_tag": "header" }
+      "context": { "element_tag": "header" },
+      "screenshot": "screenshot-1711800000-ab3kf.png"
     }
   ]
 }
 ```
 
-Each task has: `id`, `type`, `status`, `description` (what to do), `file`, `line`, `component`, and optionally `action` and `context` with element details.
+Each task has: `id`, `type`, `status`, `description` (what to do), `file`, `line`, `component`, and optionally `action`, `context` with element details, and `screenshot` with a filename.
+
+### Screenshot reference
+
+Some tasks include a `screenshot` field. The screenshot shows exactly what the user sees in the browser. To view it:
+
+```bash
+annotask screenshot TASK_ID
+```
+
+This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code.
 
 ### 2. Process each pending task
 
@@ -80,10 +72,12 @@ Filter for `status: "pending"` tasks. For each:
 
 - **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements.
 
-- **`style_update`**: Apply CSS property change. `property` and `after` values tell you what to set. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
+- **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
 
 - **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints.
 
+- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID), `impact`, `help` (what to fix), `helpUrl` (WCAG reference), and `elements` array with `html` snippets, `selector`, `fix` suggestions, and source `file`/`line`/`component`.
+
 - **`theme_update`**: A design token value change from the Theme page. The `context` object contains:
   - `category`: which token category (`colors`, `typography.families`, `typography.scale`, `spacing`, `borders.radius`)
   - `role`: semantic role name (e.g., `primary`, `background`, `heading`)
@@ -102,12 +96,10 @@ Filter for `status: "pending"` tasks. For each:
 
 ### 3. Mark tasks as ready for review
 
-After applying each task, mark it:
+After applying each task:
 
 ```bash
-curl -s -X PATCH $BASE_URL/__annotask/api/tasks/TASK_ID \
-  -H "Content-Type: application/json" \
-  -d '{"status": "review"}'
+annotask update-task TASK_ID --status=review
 ```
 
 ### 4. Report to the user
@@ -125,7 +117,11 @@ If there are tasks with `status: "denied"` and a `feedback` field, the user reje
 
 ## Also check the live report
 
-The real-time report at `$BASE_URL/__annotask/api/report` contains the current session's markup. Use this as additional context — it shows what's on the user's screen right now. But tasks are the source of truth for what to apply.
+```bash
+annotask report
+```
+
+This returns both the live report (current session markup) and tasks. Use it as additional context — it shows what's on the user's screen right now. But tasks are the source of truth for what to apply.
 
 ## Task lifecycle
 

package/skills/annotask-init/SKILL.md

@@ -122,7 +122,36 @@ Search for:
 
 Use roles: `sm`, `md`, `lg`, `xl`, `full` (match by name or ascending size).
 
-### 6. Detect icon library
+### 6. Scan breakpoints
+
+Detect responsive breakpoints from whatever styling system the project uses. Output as a flat object mapping name → min-width value.
+
+**Sources (check in order):**
+
+1. **Tailwind v4** (>= 4): Look in CSS files for `@theme` blocks defining `--breakpoint-*` custom properties, or `@custom-media` rules.
+
+2. **Tailwind v3** (< 4): Read `tailwind.config.{js,ts,mjs}`. Extract `theme.screens` or `theme.extend.screens`. Default Tailwind screens: `{ "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }` — use these as fallback if Tailwind is detected but no custom screens are defined.
+
+3. **Bootstrap**: Check for `bootstrap` in package.json. Default Bootstrap breakpoints: `{ "sm": "576px", "md": "768px", "lg": "992px", "xl": "1200px", "xxl": "1400px" }`.
+
+4. **CSS custom properties**: Search `:root` for variables containing `breakpoint`, `screen`, `bp` in the name (e.g., `--bp-mobile: 480px`).
+
+5. **CSS `@media` patterns**: Scan `.css`, `.scss`, `.vue` files for `@media` queries with `min-width` or `max-width`. Extract the 3–6 most common breakpoint values and assign roles by ascending size: `sm`, `md`, `lg`, `xl`, `2xl`.
+
+**Output example:**
+```json
+"breakpoints": {
+  "sm": "640px",
+  "md": "768px",
+  "lg": "1024px",
+  "xl": "1280px",
+  "2xl": "1536px"
+}
+```
+
+If no breakpoints are detected, omit the `breakpoints` field (don't include an empty object).
+
+### 7. Detect icon library
 
 Check `package.json` dependencies for:
 
@@ -136,7 +165,7 @@ Check `package.json` dependencies for:
 
 Read the version from package.json.
 
-### 7. Detect component library
+### 8. Detect component library
 
 Check `package.json` dependencies for:
 
@@ -157,7 +186,7 @@ grep -rh "from '${package}" --include='*.vue' --include='*.ts' --include='*.js'
 
 Extract component names from the imports. Read the version from package.json.
 
-### 8. Write design spec
+### 9. Write design spec
 
 Create `.annotask/design-spec.json`:
 
@@ -190,6 +219,13 @@ Create `.annotask/design-spec.json`:
       { "role": "md", "value": "8px", "cssVar": "--radius-md", "source": "var(--radius-md)", "sourceFile": "src/assets/main.css", "sourceLine": 25 }
     ]
   },
+  "breakpoints": {
+    "sm": "640px",
+    "md": "768px",
+    "lg": "1024px",
+    "xl": "1280px",
+    "2xl": "1536px"
+  },
   "icons": {
     "library": "lucide",
     "version": "0.300.0"
@@ -202,11 +238,11 @@ Create `.annotask/design-spec.json`:
 }
 ```
 
-### 9. Clean up old config
+### 10. Clean up old config
 
 If `.annotask/config.json` exists, delete it — it's been replaced by `design-spec.json`.
 
-### 10. Update .gitignore
+### 11. Update .gitignore
 
 Check if `.gitignore` contains `.annotask/`. If not, append:
 ```
@@ -214,7 +250,7 @@ Check if `.gitignore` contains `.annotask/`. If not, append:
 .annotask/
 ```
 
-### 11. Report to user
+### 12. Report to user
 
 Tell the user:
 - What was detected (framework, number of color/typography/spacing tokens, libraries)

package/skills/annotask-watch/SKILL.md

@@ -16,19 +16,21 @@ Connect to the Annotask WebSocket and stream changes as the user makes them visu
 
 ## Steps
 
-0. **Discover server URL** — read `.annotask/server.json` in the current working directory only (never parent directories):
+0. **Check server status**:
    ```bash
-   cat .annotask/server.json
+   annotask status
    ```
-   Use the `url` value as the server URL. If the file contains a `"mfe"` field, this is a micro-frontend setup — the server is running on a remote root shell. Save the `mfe` value for filtering. If not found, probe `curl -s http://localhost:24678/__annotask/api/status` then `curl -s http://localhost:5173/__annotask/api/status`. **Do NOT read server.json from parent or sibling directories.**
+   If this fails, the Annotask dev server isn't running. Ask the user to start it.
 
-1. **Start watching** by running in the background:
+1. **Start watching**:
    ```bash
-   npx @annotask/cli watch --port=PORT
+   annotask watch
    ```
-   Or if the CLI isn't installed, poll the HTTP API:
+   This connects to the Annotask WebSocket and streams changes in real-time. If the CLI isn't installed globally, use `npx annotask watch`.
+
+   For a one-time snapshot instead of live streaming:
    ```bash
-   curl -s $BASE_URL/__annotask/api/report
+   annotask report
    ```
 
 2. **Describe what you see** — as changes come in, summarize them in plain language: