@pencil-agent/nano-pencil 2.0.0-beta.8 → 2.0.0

package/dist/extensions/builtin/browser/agent-workspace/domain-skills/shopify-admin/README.md

@@ -1,36 +1,36 @@
-# shopify-admin
-
-Browser-harness patterns for `admin.shopify.com` and embedded Shopify apps.
-
-## Files in this folder
-
-- `embedded-apps.md` — every Shopify app runs in an iframe; how to target it
-- `polaris-inputs.md` — Polaris React inputs reject synthetic value setters; use CDP type_text
-- `knowledge-base.md` — automating the Shopify Knowledge Base App for FAQ entries
-
-## When to use these
-
-You're driving Shopify admin and need to add / edit / configure something. The Shopify admin UI is large and many surfaces are embedded apps — first check whether what you need is in an embedded app (most apps under `admin.shopify.com/store/<store>/apps/<app-slug>/...` are).
-
-## When to skip
-
-- If the operation is read-only product / inventory data → use the **Storefront API** (HTTP) instead, much faster
-- If the store has a custom admin app with API token provisioned → use the **Admin API** (GraphQL or REST) instead, no UI scraping
-- If you're editing theme code → use the **Shopify CLI** (`shopify theme push`) — don't touch the theme editor UI
-
-The browser is the right tool only when:
-- The setting / app exposes no API
-- The change is one-time or rare enough not to justify scripting
-- You're discovering / exploring the admin (e.g., finding selectors for a future automation)
-
-## Authentication
-
-Mike (or the human owner) must be logged into `admin.shopify.com` in the Chrome session that browser-harness attaches to. The harness does NOT log in — it inherits the human's session.
-
-If you hit `accounts.shopify.com` redirect, stop and ask the human to log in. Don't type credentials.
-
-## Polaris is in transition (Jan 2026 onward)
-
-Shopify is migrating its design system from React-based Polaris to Web-Components-based Polaris. Most legacy admin surfaces are still React. Newer surfaces (Catalog Mapping, parts of Settings) may be web components.
-
-Screenshot first. If you see `<s-text-field>` or `<s-button>` web component tags → use the web component pattern. If you see `[class*="Polaris-"]` React class names → use the CDP keystrokes pattern in `polaris-inputs.md`.
+# shopify-admin
+
+Browser-harness patterns for `admin.shopify.com` and embedded Shopify apps.
+
+## Files in this folder
+
+- `embedded-apps.md` — every Shopify app runs in an iframe; how to target it
+- `polaris-inputs.md` — Polaris React inputs reject synthetic value setters; use CDP type_text
+- `knowledge-base.md` — automating the Shopify Knowledge Base App for FAQ entries
+
+## When to use these
+
+You're driving Shopify admin and need to add / edit / configure something. The Shopify admin UI is large and many surfaces are embedded apps — first check whether what you need is in an embedded app (most apps under `admin.shopify.com/store/<store>/apps/<app-slug>/...` are).
+
+## When to skip
+
+- If the operation is read-only product / inventory data → use the **Storefront API** (HTTP) instead, much faster
+- If the store has a custom admin app with API token provisioned → use the **Admin API** (GraphQL or REST) instead, no UI scraping
+- If you're editing theme code → use the **Shopify CLI** (`shopify theme push`) — don't touch the theme editor UI
+
+The browser is the right tool only when:
+- The setting / app exposes no API
+- The change is one-time or rare enough not to justify scripting
+- You're discovering / exploring the admin (e.g., finding selectors for a future automation)
+
+## Authentication
+
+Mike (or the human owner) must be logged into `admin.shopify.com` in the Chrome session that browser-harness attaches to. The harness does NOT log in — it inherits the human's session.
+
+If you hit `accounts.shopify.com` redirect, stop and ask the human to log in. Don't type credentials.
+
+## Polaris is in transition (Jan 2026 onward)
+
+Shopify is migrating its design system from React-based Polaris to Web-Components-based Polaris. Most legacy admin surfaces are still React. Newer surfaces (Catalog Mapping, parts of Settings) may be web components.
+
+Screenshot first. If you see `<s-text-field>` or `<s-button>` web component tags → use the web component pattern. If you see `[class*="Polaris-"]` React class names → use the CDP keystrokes pattern in `polaris-inputs.md`.

package/dist/extensions/builtin/browser/agent-workspace/domain-skills/shopify-admin/embedded-apps.md

@@ -1,72 +1,72 @@
-# Shopify embedded apps run in iframes
-
-Every Shopify app surfaced in the admin (first-party like Knowledge Base, third-party like Okendo) renders inside a sandboxed iframe. Your top-level `document` queries find the Shopify chrome (sidebar, header, search bar) but **none of the app's UI**.
-
-## How to target the iframe
-
-```python
-from helpers import iframe_target, js, type_text
-
-# 1. Find the iframe by URL substring
-tid = iframe_target("qa-pairs-app")  # Knowledge Base App
-
-# 2. Run JS inside the iframe by passing target_id
-result = js("""
-(() => {
-  const button = Array.from(document.querySelectorAll('button')).find(b => b.textContent.trim() === 'Add FAQ');
-  if (button) { button.click(); return {clicked: true}; }
-  return {clicked: false};
-})()
-""", target_id=tid)
-```
-
-## Finding the URL substring
-
-The iframe's URL contains the app slug. Run:
-
-```python
-import json
-for t in cdp("Target.getTargets")["targetInfos"]:
-    if t["type"] == "iframe" and "shopify" in t.get("url", "").lower():
-        print(t["url"])
-```
-
-Then pick a substring unique to your target app.
-
-## Known Shopify app iframe slugs
-
-| App | iframe URL substring |
-|---|---|
-| Shopify Knowledge Base (qa-pairs-app) | `qa-pairs-app` |
-| Shopify Online Store editor | `online-store-web.shopifyapps.com` |
-| Shopify Hydrogen Storefront | `hydrogen-storefronts` (or similar — verify) |
-
-Add to this table when you discover new ones.
-
-## Why iframes
-
-Shopify uses App Bridge to embed third-party apps with isolation. Your top-level page CAN'T directly access app DOM for security reasons — you need iframe targeting (which the harness does via CDP `Target.attachToTarget`).
-
-## Coordinate clicks vs JS clicks
-
-Coordinate clicks (`click(x, y)`) pass through iframes at the compositor level — they work. But JS clicks scoped to the iframe target are more reliable for routine button taps because:
-
-- Element text content is stable across UI redesigns
-- DPR scaling on retina is automatic
-- React event handlers are guaranteed to fire (vs. CDP mouse events which sometimes hit a transparent layer above the button)
-
-## Gotcha — multiple iframes from same app
-
-The Online Store editor renders the storefront preview AND the editor toolbar in two separate iframes. Pick the right one by URL substring; don't assume the first match is correct.
-
-```python
-# WRONG — picks first match
-tid = iframe_target("online-store-web")
-
-# RIGHT — disambiguate
-for t in cdp("Target.getTargets")["targetInfos"]:
-    url = t.get("url", "")
-    if "online-store-web" in url and "editor" in url:
-        tid = t["targetId"]
-        break
-```
+# Shopify embedded apps run in iframes
+
+Every Shopify app surfaced in the admin (first-party like Knowledge Base, third-party like Okendo) renders inside a sandboxed iframe. Your top-level `document` queries find the Shopify chrome (sidebar, header, search bar) but **none of the app's UI**.
+
+## How to target the iframe
+
+```python
+from helpers import iframe_target, js, type_text
+
+# 1. Find the iframe by URL substring
+tid = iframe_target("qa-pairs-app")  # Knowledge Base App
+
+# 2. Run JS inside the iframe by passing target_id
+result = js("""
+(() => {
+  const button = Array.from(document.querySelectorAll('button')).find(b => b.textContent.trim() === 'Add FAQ');
+  if (button) { button.click(); return {clicked: true}; }
+  return {clicked: false};
+})()
+""", target_id=tid)
+```
+
+## Finding the URL substring
+
+The iframe's URL contains the app slug. Run:
+
+```python
+import json
+for t in cdp("Target.getTargets")["targetInfos"]:
+    if t["type"] == "iframe" and "shopify" in t.get("url", "").lower():
+        print(t["url"])
+```
+
+Then pick a substring unique to your target app.
+
+## Known Shopify app iframe slugs
+
+| App | iframe URL substring |
+|---|---|
+| Shopify Knowledge Base (qa-pairs-app) | `qa-pairs-app` |
+| Shopify Online Store editor | `online-store-web.shopifyapps.com` |
+| Shopify Hydrogen Storefront | `hydrogen-storefronts` (or similar — verify) |
+
+Add to this table when you discover new ones.
+
+## Why iframes
+
+Shopify uses App Bridge to embed third-party apps with isolation. Your top-level page CAN'T directly access app DOM for security reasons — you need iframe targeting (which the harness does via CDP `Target.attachToTarget`).
+
+## Coordinate clicks vs JS clicks
+
+Coordinate clicks (`click(x, y)`) pass through iframes at the compositor level — they work. But JS clicks scoped to the iframe target are more reliable for routine button taps because:
+
+- Element text content is stable across UI redesigns
+- DPR scaling on retina is automatic
+- React event handlers are guaranteed to fire (vs. CDP mouse events which sometimes hit a transparent layer above the button)
+
+## Gotcha — multiple iframes from same app
+
+The Online Store editor renders the storefront preview AND the editor toolbar in two separate iframes. Pick the right one by URL substring; don't assume the first match is correct.
+
+```python
+# WRONG — picks first match
+tid = iframe_target("online-store-web")
+
+# RIGHT — disambiguate
+for t in cdp("Target.getTargets")["targetInfos"]:
+    url = t.get("url", "")
+    if "online-store-web" in url and "editor" in url:
+        tid = t["targetId"]
+        break
+```

package/dist/extensions/builtin/browser/agent-workspace/domain-skills/shopify-admin/knowledge-base.md

@@ -1,109 +1,109 @@
-# Shopify Knowledge Base App — automating FAQ entries
-
-The Knowledge Base App (Shopify Winter '26 Edition) lets merchants control how AI agents (ChatGPT, Perplexity, Claude, Copilot, Gemini) answer questions about their brand. Each entry is a Question / Answer pair. The app currently has no public API and is English-only as of Winter '26 — browser automation is the canonical path.
-
-## URL pattern
-
-```
-https://admin.shopify.com/store/<store-handle>/apps/shopify-knowledge-base/app
-```
-
-Sub-routes:
-- `/app` — overview (FAQ list, top unanswered questions, query log)
-- `/app/new` — Add FAQ form
-- `/app/pairs/<id>` — entry detail / edit
-
-## Iframe slug
-
-The app runs at iframe URL containing `qa-pairs-app`:
-
-```python
-tid = iframe_target("qa-pairs-app")
-```
-
-## Adding a single FAQ
-
-See `polaris-inputs.md` for the full canonical pattern. Quick version:
-
-```python
-def add_faq(question, answer):
-    tid = iframe_target("qa-pairs-app")
-    # focus question input via JS, type via CDP, focus answer, type, click Save
-    # poll URL for /pairs/<id> success signal
-```
-
-## Batching multiple FAQs
-
-After saving an entry, the success page shows "FAQ created. Add another FAQ" link. Click it via JS to skip navigating back to overview:
-
-```python
-def click_add_another():
-    tid = iframe_target("qa-pairs-app")
-    js("""
-    (() => {
-      const link = Array.from(document.querySelectorAll('a, button'))
-        .find(x => x.textContent.trim() === 'Add another FAQ');
-      if (link) link.click();
-    })()
-    """, target_id=tid)
-```
-
-Loop:
-
-```python
-ENTRIES = [(q1, a1), (q2, a2), ...]
-for q, a in ENTRIES:
-    click_add_another()
-    time.sleep(1.5)  # wait for form to render
-    ok, info = add_faq(q, a)
-    print(f"{q[:40]} -> {ok} ({info})")
-    if not ok: break
-```
-
-## Brand voice — what to put in answers
-
-This is application-specific (depends on the merchant). For JING the rule was Aesop founder-letter tone — sentence case, no exclamation points, "JING" not "we", specific over generic.
-
-The Shopify guidance "Provide a brief answer in 1 or 2 sentences" is a soft hint. The textarea accepts longer text and AI agents prefer specific multi-sentence answers. Aim for 2-4 short sentences with concrete details.
-
-## What to put in the Knowledge Base
-
-Categories that materially shape AI agent answers about your brand:
-
-1. **Brand voice / DNA** — "What is your brand?" / "What's your tone?"
-2. **Specs** — exact materials, dimensions, weights, sizes (NOT marketing prose)
-3. **Comparisons** — "How does X compare to <competitor>?" with concrete differences
-4. **Policies** — returns, shipping, care, warranty, contact (in brand voice)
-5. **Origin** — founder, where made, why brand exists
-6. **Limitations** — what you DON'T do (V1 scope, US-only, etc.) — agents that hallucinate availability hurt conversion
-
-Skip: anything marketing-speak. The Knowledge Base is for **truth, in voice**, not pitch copy.
-
-## Top unanswered questions
-
-The overview shows up to 7 "Top unanswered questions" Shopify auto-detected from query logs. **Answer these first** — they're real shopper queries hitting your store right now. Once answered, the section empties.
-
-## Query log
-
-`/admin/apps/shopify-knowledge-base/app/queries` (or "Query log" in app sidebar) shows what shoppers actually asked AI agents about your brand. Read weekly. New patterns become new FAQ entries.
-
-## Verifying entries surface in AI
-
-After adding an entry, allow 24 hours for AI provider indexing, then test:
-
-- ChatGPT: "Tell me about <your brand>'s return policy" → check if your exact wording surfaces
-- Perplexity: same
-- Claude: "Compare <your brand> vs <competitor>" → see if your comparison framing appears
-
-If the answer doesn't surface, the entry might be too long, too vague, or contradicted by another source (your homepage, an outdated blog post). Tighten the answer.
-
-## Limits
-
-As of Winter '26 Edition:
-- English-only
-- No bulk import / CSV upload
-- No API for read or write
-- Each entry maximum ~500 words (soft cap; UI shows guidance "1 or 2 sentences")
-- No version history visible to the merchant
-
-Watch Shopify changelogs for API exposure — likely in Spring '26 or Summer '26 Edition. When it ships, switch to API-driven population.
+# Shopify Knowledge Base App — automating FAQ entries
+
+The Knowledge Base App (Shopify Winter '26 Edition) lets merchants control how AI agents (ChatGPT, Perplexity, Claude, Copilot, Gemini) answer questions about their brand. Each entry is a Question / Answer pair. The app currently has no public API and is English-only as of Winter '26 — browser automation is the canonical path.
+
+## URL pattern
+
+```
+https://admin.shopify.com/store/<store-handle>/apps/shopify-knowledge-base/app
+```
+
+Sub-routes:
+- `/app` — overview (FAQ list, top unanswered questions, query log)
+- `/app/new` — Add FAQ form
+- `/app/pairs/<id>` — entry detail / edit
+
+## Iframe slug
+
+The app runs at iframe URL containing `qa-pairs-app`:
+
+```python
+tid = iframe_target("qa-pairs-app")
+```
+
+## Adding a single FAQ
+
+See `polaris-inputs.md` for the full canonical pattern. Quick version:
+
+```python
+def add_faq(question, answer):
+    tid = iframe_target("qa-pairs-app")
+    # focus question input via JS, type via CDP, focus answer, type, click Save
+    # poll URL for /pairs/<id> success signal
+```
+
+## Batching multiple FAQs
+
+After saving an entry, the success page shows "FAQ created. Add another FAQ" link. Click it via JS to skip navigating back to overview:
+
+```python
+def click_add_another():
+    tid = iframe_target("qa-pairs-app")
+    js("""
+    (() => {
+      const link = Array.from(document.querySelectorAll('a, button'))
+        .find(x => x.textContent.trim() === 'Add another FAQ');
+      if (link) link.click();
+    })()
+    """, target_id=tid)
+```
+
+Loop:
+
+```python
+ENTRIES = [(q1, a1), (q2, a2), ...]
+for q, a in ENTRIES:
+    click_add_another()
+    time.sleep(1.5)  # wait for form to render
+    ok, info = add_faq(q, a)
+    print(f"{q[:40]} -> {ok} ({info})")
+    if not ok: break
+```
+
+## Brand voice — what to put in answers
+
+This is application-specific (depends on the merchant). For JING the rule was Aesop founder-letter tone — sentence case, no exclamation points, "JING" not "we", specific over generic.
+
+The Shopify guidance "Provide a brief answer in 1 or 2 sentences" is a soft hint. The textarea accepts longer text and AI agents prefer specific multi-sentence answers. Aim for 2-4 short sentences with concrete details.
+
+## What to put in the Knowledge Base
+
+Categories that materially shape AI agent answers about your brand:
+
+1. **Brand voice / DNA** — "What is your brand?" / "What's your tone?"
+2. **Specs** — exact materials, dimensions, weights, sizes (NOT marketing prose)
+3. **Comparisons** — "How does X compare to <competitor>?" with concrete differences
+4. **Policies** — returns, shipping, care, warranty, contact (in brand voice)
+5. **Origin** — founder, where made, why brand exists
+6. **Limitations** — what you DON'T do (V1 scope, US-only, etc.) — agents that hallucinate availability hurt conversion
+
+Skip: anything marketing-speak. The Knowledge Base is for **truth, in voice**, not pitch copy.
+
+## Top unanswered questions
+
+The overview shows up to 7 "Top unanswered questions" Shopify auto-detected from query logs. **Answer these first** — they're real shopper queries hitting your store right now. Once answered, the section empties.
+
+## Query log
+
+`/admin/apps/shopify-knowledge-base/app/queries` (or "Query log" in app sidebar) shows what shoppers actually asked AI agents about your brand. Read weekly. New patterns become new FAQ entries.
+
+## Verifying entries surface in AI
+
+After adding an entry, allow 24 hours for AI provider indexing, then test:
+
+- ChatGPT: "Tell me about <your brand>'s return policy" → check if your exact wording surfaces
+- Perplexity: same
+- Claude: "Compare <your brand> vs <competitor>" → see if your comparison framing appears
+
+If the answer doesn't surface, the entry might be too long, too vague, or contradicted by another source (your homepage, an outdated blog post). Tighten the answer.
+
+## Limits
+
+As of Winter '26 Edition:
+- English-only
+- No bulk import / CSV upload
+- No API for read or write
+- Each entry maximum ~500 words (soft cap; UI shows guidance "1 or 2 sentences")
+- No version history visible to the merchant
+
+Watch Shopify changelogs for API exposure — likely in Spring '26 or Summer '26 Edition. When it ships, switch to API-driven population.