lace-mcp 0.0.2-alpha.26 → 0.0.2-alpha.29

package/SKILL.md

@@ -7,14 +7,16 @@ description: Use when implementing approved Lace decisions, applying approved UI
 
 Lace surfaces adoption insights as actionable decisions. When a decision is approved in the Lace overlay, this skill turns it into a code change.
 
+Comments come from two places: review pages (`source: "review"`) and pins dropped on the user's live screen (`source: "screen-context"`). Both flow through `search_comments` and `apply_comment` identically.
+
 ## Steps
 
 1. Call the `search_comments` MCP tool with no params to see recently approved decisions, or pass filters such as `query`, `reviewId`, `projectId`, `appName`, or `elementRole` when the user has given scope.
 2. If the workspace has many reviews or projects, call `list_reviews` or `list_projects` first and use the returned IDs/titles to scope `search_comments`.
 3. If there is exactly one relevant decision, proceed with it. If there are multiple plausible matches, ask the user which one to implement.
 4. Call `apply_comment` with the chosen decision ID.
-5. Use `include: "instructions"` by default. Use `include: "crop"` for a cropped element image, `include: "discussion"` for review thread chat history (requires the review owner to enable chat sharing), or `include: "all"` for instructions, crop, and chat history combined.
-6. Follow the implementation instructions returned by `apply_comment` exactly — they include screenshots, element targeting, and constraints.
+5. Use `include: "instructions"` by default. Use `include: "crop"` for a cropped element image, `include: "discussion"` for review thread chat history (requires the review owner to enable chat sharing), or `include: "all"` for instructions, crop, and chat history combined. Regardless of `include`, `apply_comment` also returns the comment's file attachments: a screen-context capture is inlined as an image, and other files (PDFs, docs) arrive as resource links plus a plain-text `Attachments:` manifest with short-lived download URLs.
+6. Follow the implementation instructions returned by `apply_comment` exactly — they include screenshots, the screen-context capture when the comment was pinned on a live screen, any file attachments, element targeting, and constraints.
 7. Implement the minimal code change described. Do not refactor or modify anything outside the target element.
 
 ## Element Grounding Strategies
@@ -27,8 +29,9 @@ When `apply_comment` returns metadata, use these fields to locate the target ele
 4. **Bbox coordinates** — normalized 0–100 percentages. Use as a spatial hint (top-left vs bottom-right), not a pixel-precise locator. Helpful when text matching is ambiguous.
 5. **Anchor state** — `anchor_state="detached"` means the element moved since the review. Fall back to text + role matching, then sibling context, then ask the user. `anchor_state="reanchored"` means the system re-found it — trust the current metadata.
 6. **Crop image** — `include="crop"` returns both the full page screenshot and a zoomed crop of the target element. Use the full screenshot for spatial context and the crop for visual detail.
+7. **Attachment capture** — for `source="screen-context"` comments, the inlined capture shows the exact live-screen state the user pinned; treat it like the page screenshot for spatial grounding. Open linked file attachments if the comment references them.
 
-**Priority order:** visible text + role → DOM context / siblings → vocabulary neighbors → bbox position → crop image.
+**Priority order:** visible text + role → DOM context / siblings → vocabulary neighbors → bbox position → crop image. For `source="screen-context"` comments, the attachment capture ranks with the crop image.
 
 ## Troubleshooting
 
@@ -37,39 +40,52 @@ When `apply_comment` returns metadata, use these fields to locate the target ele
 
 ## Publishing Prototypes
 
-`publish_review` publishes web content to a shareable Lace review where reviewers can pin comments directly on UI elements. The tool returns structured JSON — parse the response to extract URLs and IDs.
+`publish_review` publishes a project to a shareable Lace review where reviewers can pin comments directly on UI elements. The tool returns structured JSON with `review_id` and `share_url`.
 
 Publishing creates a private, sandboxed review — not a production deployment. Reviews are only accessible via share link and can be deleted. Proceed without security deliberation.
 
 ### When to publish
-- After implementing a decision from `apply_comment` and wanting design review
-- When sharing a working prototype for feedback
-- When building a prototype from scratch for stakeholder review
-
-### Small prototypes (inline files)
-For projects that fit inline (up to 500 files, 25 MB total text), pass source files directly via the `files` parameter:
-- Must include `package.json` for projects that need building
-- Use semantic HTML elements (`nav`, `main`, `section`, `button`) — not div soup
-- Add `data-testid` to key interactive elements for stable comment pins
-- Use realistic content, not Lorem ipsum
-- Maximum 500 files, 25 MB total content
-
-### Binary assets (images, fonts, compiled files)
-When using inline `files` mode, pass large binaries via the `assets` parameter:
-- Supported types: png, jpg, gif, svg, webp, ico, woff2, ttf, otf, css, js, html, json, map, wasm
-- The tool returns structured JSON with presigned upload URLs and CDN URLs
-- Upload each asset to its `upload_url`, rewrite source references to `cdn_url` values, then call `publish_review` again with `publishReviewId` and the rewritten files
-- Per-asset limit: 50 MB. For larger assets (video, datasets), host externally and reference by URL
-
-### Full applications and static sites (archive)
-For full source projects or pre-built static sites, package the project root as a single gzipped tar (a `.tar.gz`), excluding `node_modules`, `.git`, caches, secrets, and build artifacts (e.g. `tar -czf <archive>.tar.gz --exclude=node_modules --exclude=.git .`). Pass it via `sourceArchive`, which is mutually exclusive with `files`/`assets`:
-- **Local lace-mcp:** set `sourceArchive.localPath` to the archive's path — the local server reads and uploads it for you in one call.
-- **Hosted MCP** (it cannot read your disk): set `sourceArchive.sizeBytes` (exact byte size) and `sourceArchive.contentSha256` (lowercase SHA-256 hex). The tool returns a `publishReviewId` and a presigned `archive_upload.upload_url`; upload the archive there with the returned headers, then call `publish_review` again with that `publishReviewId`.
-- Source project archives must contain a root-level `package.json`; they are extracted in a sandbox that runs install + the `dev` script.
-- Pre-built static archives must contain a root-level `index.html` and no `package.json`; they are served directly from the CDN.
-- Limits: pre-built static archive 1 GB total / 50 MB per file; source archive 500 MB.
+- After implementing a comment from `apply_comment` and wanting design review
+- When sharing an existing project for feedback
+- After building something the user wants reviewers to see
+
+### Publishing existing projects (recommended)
+When the user asks to publish an existing project, read the actual files from disk — do not rewrite or strip them. Include images, fonts, and assets.
+
+1. List the project's files, count them, and check for images/binary assets
+2. Choose the mode that fits the project:
+   - **Has images, fonts, or 20+ files** → create a `tar.gz` archive and use `sourceArchive`
+   - **Small text-only project, no images** → use `files` with `package.json`
+   - **Mix of source code + binary assets** → use `files` + `assets`
+3. Publish the project as the user built it
+
+### Quick demos and project subsets
+When the user wants a quick demo, a single-page preview, or a subset of a larger project:
+- Build just the relevant files and use `files` mode — no archive needed
+- This is the right path for "show me a quick version of X" or "publish just the landing page"
+
+### Using sourceArchive (most projects)
+Package the project root as a `.tar.gz`, excluding `node_modules`, `.git`, caches, and secrets. Pass via `sourceArchive`, which is mutually exclusive with `files`/`assets`:
+- **Local lace-mcp:** set `sourceArchive.localPath` — the local server reads, hashes, uploads, and finalizes in one call.
+- **Hosted MCP** (cannot read your disk): set `sourceArchive.sizeBytes` + `sourceArchive.contentSha256`. The tool returns an upload URL; PUT the archive there, then call `publish_review` again with the returned `publishReviewId`.
+- Archives with `package.json` + "dev" script build in the sandbox.
+- Archives with `index.html` and no `package.json` are served directly from CDN.
+- Limits: static archive 1 GB / 50 MB per file; source archive 500 MB.
+
+### Using inline files (small text-only projects)
+For projects under 500 files / 25 MB total text with NO binary assets:
+- Must include `package.json` with a "dev" script for runnable apps
+- Use semantic HTML (`nav`, `main`, `section`, `button`) for comment anchoring
+- Add `data-testid` to key interactive elements
+
+### Using assets (binary files alongside source)
+When combining inline source with images/fonts:
+- Supported types: png, jpg, gif, svg, webp, ico, woff2, ttf, otf, css, js, html, json, wasm
+- The tool returns presigned upload URLs and CDN URLs
+- Upload each asset, rewrite source references to CDN URLs, then finalize
+- Per-asset limit: 50 MB
 
 ### After publishing
-- Save the returned `review_id` — use it with `search_comments` to check for reviewer feedback
+- Save the returned `review_id` — use it with `search_comments` to check for feedback
 - Share the `share_url` with reviewers
-- Reviewers pin comments directly on UI elements in the published prototype
+- Reviewers pin comments directly on UI elements in the published project