@nextclaw/x-harness 0.0.0-stage → 0.1.1

package/generated/observation.mjs

@@ -0,0 +1,515 @@
+// Generated by packages/x-harness/scripts/generate-observation.mjs; edit TS reader owners only.
+export const readXObservation = (query) => {
+  const readPosts = function readPosts({ offset = 0, limit = 5, targetId = "", } = {}) {
+    if (!Number.isInteger(offset) ||
+        offset < 0 ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 5)
+        throw new Error("offset>=0；limit为1～5");
+    if (targetId && !/^\d+$/.test(targetId))
+        throw new Error("targetId必须是数字公开ID");
+    const visible = (el) => el.getClientRects().length > 0;
+    const primaryTime = (a) => Array.from(a.querySelectorAll("time")).find((t) => visible(t) &&
+        /\/status\/\d+(?:$|[/?#])/.test(t.closest("a")?.getAttribute("href") ?? "")) ?? null;
+    const all = Array.from(document.querySelectorAll("article")).filter(visible);
+    const candidates = targetId
+        ? all.filter((a) => {
+            const primary = primaryTime(a)?.closest("a")?.getAttribute("href");
+            return (primary && new RegExp(`/status/${targetId}(?:$|[/?#])`).test(primary));
+        })
+        : all;
+    const posts = candidates.slice(offset, offset + limit).map((a) => {
+        const time = primaryTime(a);
+        const primary = time?.closest("a")?.getAttribute("href") ?? null;
+        const links = [
+            ...new Set(Array.from(a.querySelectorAll("a[href]"))
+                .filter(visible)
+                .map((l) => l.getAttribute("href"))),
+        ];
+        const buttons = Array.from(a.querySelectorAll("button"))
+            .filter(visible)
+            .map((b) => ({
+            label: b.getAttribute("aria-label") || b.innerText,
+            disabled: b.hasAttribute("disabled"),
+        }));
+        const text = a.innerText;
+        const datetime = time?.getAttribute("datetime") ?? null;
+        const id = primary?.match(/\/status\/(\d+)/)?.[1] ?? null;
+        const author = primary?.match(/\/([^/]+)\/status\//)?.[1] ?? null;
+        const images = Array.from(a.querySelectorAll('[data-testid="tweetPhoto"] img'))
+            .filter(visible)
+            .map((img) => ({
+            alt: img.getAttribute("alt"),
+            src: img.getAttribute("src"),
+        }));
+        const media = Array.from(a.querySelectorAll('[data-testid="videoPlayer"],video'))
+            .filter(visible)
+            .map((el) => ({
+            kind: "video",
+            label: el.getAttribute("aria-label"),
+            poster: el.getAttribute("poster"),
+            requiresViewing: true,
+        }));
+        return {
+            id,
+            author,
+            datetime,
+            primary,
+            text,
+            links,
+            buttons,
+            // View/quote counts may be visible links rather than buttons; collect in this same read.
+            metrics: [
+                ...buttons,
+                ...Array.from(a.querySelectorAll('a[href$="/analytics"],a[href$="/quotes"]'))
+                    .filter(visible)
+                    .map((link) => ({
+                    label: link.getAttribute("aria-label") ||
+                        `${link.getAttribute("href").endsWith("/analytics") ? "观看" : "引用"} ${link.innerText}`,
+                })),
+            ],
+            images,
+            media,
+            needsExpansion: /显示更多|Show more/i.test(text),
+            missing: [
+                !id && "id",
+                !author && "author",
+                !datetime && "datetime",
+                !text && "text",
+            ].filter(Boolean),
+        };
+    });
+    const versionLinks = Array.from(document.querySelectorAll("a[href]"))
+        .filter(visible)
+        .filter((a) => /最新版本|查看最新帖子|Latest version|View latest/i.test(a.innerText))
+        .slice(0, 5)
+        .map((a) => ({ label: a.innerText, href: a.getAttribute("href") }));
+    const emptyEvidence = all.length === 0
+        ? [
+            ...new Set(Array.from(document.querySelectorAll("main span"))
+                .filter(visible)
+                .map((e) => e.innerText?.trim())
+                .filter((text) => text &&
+                text.length <= 400 &&
+                !text.includes("\n") &&
+                /^(?:没有.*结果|未找到.*结果|No results for)/i.test(text))),
+        ].slice(0, 2)
+        : [];
+    return {
+        renderedArticles: all.length,
+        matched: candidates.length,
+        offset,
+        moreInDOM: candidates.length > offset + posts.length,
+        pageComplete: false,
+        needsStateCheck: all.length === 0 && emptyEvidence.length === 0,
+        posts,
+        versionLinks,
+        emptyEvidence,
+        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
+            .filter(visible)
+            .map((e) => e.innerText),
+    };
+};
+  const readProfile = function readProfile({ handle } = {}) {
+    if (!/^[A-Za-z0-9_]{1,15}$/.test(handle ?? ""))
+        throw new Error("需要已观察的X handle");
+    const visible = (el) => el.getClientRects().length > 0;
+    const main = document.querySelector("main");
+    if (!main)
+        return {
+            handle,
+            blue: null,
+            relationship: "unknown",
+            alerts: ["missing-main"],
+            observedAt: new Date().toISOString(),
+        };
+    const buttons = Array.from(main.querySelectorAll("button")).filter(visible);
+    const labels = buttons.map((b) => b.getAttribute("aria-label") || b.innerText);
+    const relationship = labels.includes(`正在关注 @${handle}`) ||
+        labels.includes(`取消关注 @${handle}`)
+        ? "following"
+        : labels.includes(`回关 @${handle}`)
+            ? "follows-you"
+            : labels.includes(`关注 @${handle}`)
+                ? "not-following"
+                : "unknown";
+    const badges = buttons
+        .filter((b) => b.getAttribute("aria-label") === "提供已验证账号的详细信息。")
+        .map((b) => b.querySelector("svg"))
+        .filter(Boolean);
+    const blue = badges.length === 1
+        ? [
+            getComputedStyle(badges[0]).color,
+            getComputedStyle(badges[0]).fill,
+        ].includes("rgb(29, 155, 240)")
+        : null;
+    const links = Array.from(main.querySelectorAll("a[href]")).filter(visible);
+    const counter = (suffixes) => {
+        const matched = links.filter((a) => suffixes.some((s) => a.getAttribute("href")?.toLowerCase() ===
+            `/${handle}/${s}`.toLowerCase()));
+        const texts = [...new Set(matched.map((a) => a.innerText.trim()))];
+        if (texts.length !== 1)
+            return { value: null, text: texts, precision: "unknown" };
+        const match = texts[0].match(/^([\d,.]+)\s*(万|亿|[KMB])?/i);
+        const factors = {
+            万: 1e4,
+            亿: 1e8,
+            K: 1e3,
+            M: 1e6,
+            B: 1e9,
+        };
+        const value = match
+            ? Number(match[1].replaceAll(",", "")) *
+                (factors[match[2]?.toUpperCase()] ?? 1)
+            : null;
+        const hrefs = [...new Set(matched.map((a) => a.getAttribute("href")))];
+        return {
+            value: Number.isFinite(value) ? value : null,
+            text: texts[0],
+            precision: match?.[2] ? "rounded" : "exact",
+            url: hrefs.length === 1 ? "https://x.com" + hrefs[0] : null,
+        };
+    };
+    return {
+        handle,
+        blue,
+        relationship,
+        relationshipControls: labels
+            .filter((label) => label.includes("@" + handle) || /取消关注|订阅/.test(label))
+            .slice(0, 5),
+        biography: main.querySelector('[data-testid="UserDescription"]')
+            ?.innerText ?? null,
+        following: counter(["following"]),
+        followers: counter(["followers", "verified_followers"]),
+        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
+            .filter(visible)
+            .map((a) => a.innerText),
+        observedAt: new Date().toISOString(),
+    };
+};
+  const readComposer = function readComposer() {
+    const visible = (el) => el.getClientRects().length > 0 && !el.closest('[aria-hidden="true"]');
+    const dialogs = Array.from(document.querySelectorAll('[role="dialog"]')).filter(visible);
+    const root = dialogs.length === 1
+        ? dialogs[0]
+        : dialogs.length === 0
+            ? document.querySelector("main")
+            : null;
+    if (location.pathname.startsWith("/compose/post/unsent/")) {
+        const text = root?.innerText ?? "";
+        return {
+            page: location.href,
+            unsent: true,
+            text: text.slice(0, 8000),
+            truncated: text.length > 8000,
+            controls: root
+                ? Array.from(root.querySelectorAll('button,a,[role="tab"]'))
+                    .filter(visible)
+                    .slice(0, 30)
+                    .map((el) => ({
+                    label: el.getAttribute("aria-label") || el.innerText,
+                    href: el.getAttribute("href"),
+                }))
+                : [],
+            needsStateCheck: !root || text.length > 8000,
+        };
+    }
+    const navigation = Array.from(document.querySelectorAll('a[href="/compose/post"],button[data-testid="SideNav_AccountSwitcher_Button"]'))
+        .filter(visible)
+        .map((el) => ({
+        role: el.tagName === "A" ? "link" : "button",
+        label: el.getAttribute("aria-label") || el.innerText,
+    }));
+    if (Array.from(document.querySelectorAll('[role="textbox"],textarea,[contenteditable="true"]')).filter(visible).length !== 1)
+        return {
+            page: location.href,
+            navigation,
+            dialog: root &&
+                (dialogs.length === 1 || location.pathname === "/compose/post/media")
+                ? {
+                    buttons: Array.from(root.querySelectorAll('button,[role="tab"]'))
+                        .filter(visible)
+                        .map((el) => ({
+                        role: el.getAttribute("role") || "button",
+                        label: el.getAttribute("aria-label") || el.innerText,
+                    })),
+                    fields: Array.from(root.querySelectorAll("textarea,input"))
+                        .filter(visible)
+                        .map((el) => ({
+                        label: el.getAttribute("aria-label"),
+                        placeholder: el.getAttribute("placeholder"),
+                        value: el.value,
+                    })),
+                }
+                : null,
+            needsStateCheck: true,
+            missing: ["composer-editor-not-found"],
+            editorCandidates: Array.from(document.querySelectorAll('[role="textbox"],textarea,[contenteditable="true"]'))
+                .filter(visible)
+                .map((el) => ({
+                label: el.getAttribute("aria-label"),
+                testId: el.getAttribute("data-testid"),
+                tag: el.tagName,
+            })),
+        };
+    const editors = Array.from(document.querySelectorAll('[role="textbox"],textarea,[contenteditable="true"]')).filter(visible);
+    let scope = editors[0];
+    while (scope.parentElement &&
+        !Array.from(scope.querySelectorAll("button")).some((el) => visible(el) &&
+            /^(发帖|回复|更新)$/.test(el.getAttribute("aria-label") || el.innerText)))
+        scope = scope.parentElement;
+    if (scope === document.body || scope === document.documentElement)
+        return {
+            page: location.href,
+            needsStateCheck: true,
+            missing: ["composer-submit-scope-not-found"],
+        };
+    return {
+        page: location.href,
+        navigation,
+        editors: editors.map((el) => ({
+            label: el.getAttribute("aria-label"),
+            testId: el.getAttribute("data-testid"),
+            text: el.innerText,
+        })),
+        buttons: Array.from(scope.querySelectorAll("button"))
+            .filter(visible)
+            .map((el) => ({
+            label: el.getAttribute("aria-label") || el.innerText,
+            disabled: el.disabled,
+            testId: el.getAttribute("data-testid"),
+            ariaDisabled: el.getAttribute("aria-disabled"),
+            ariaBusy: el.getAttribute("aria-busy"),
+        })),
+        images: Array.from(scope.querySelectorAll("img"))
+            .filter(visible)
+            .map((el) => ({ alt: el.alt })),
+        needsStateCheck: false,
+    };
+};
+  const readMediaEditor = function readMediaEditor() {
+    if (location.pathname !== "/compose/post/media")
+        return { needsStateCheck: true, missing: ["media-route-not-found"] };
+    const visible = (el) => el.getClientRects().length > 0 && !el.closest('[aria-hidden="true"]');
+    const controls = Array.from(document.querySelectorAll('button,[role="tab"]'))
+        .filter(visible)
+        .map((el) => ({
+        role: el.getAttribute("role") || "button",
+        label: el.getAttribute("aria-label") || el.innerText,
+        disabled: el.disabled === true,
+    }));
+    const fields = Array.from(document.querySelectorAll('textarea,input,[role="textbox"]'))
+        .filter(visible)
+        .map((el) => ({
+        label: el.getAttribute("aria-label"),
+        placeholder: el.getAttribute("placeholder"),
+        value: el.value ?? el.innerText,
+    }));
+    const ready = controls.some((c) => c.role === "button" && c.label === "保存") &&
+        controls.some((c) => c.role === "tab" && c.label === "编辑图片描述");
+    return {
+        page: location.href,
+        controls: controls.slice(0, 20),
+        fields: fields.slice(0, 5),
+        needsStateCheck: !ready || controls.length > 20 || fields.length > 5,
+        missing: ready ? [] : ["media-editor-controls-not-ready"],
+        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
+            .filter(visible)
+            .map((el) => el.innerText),
+    };
+};
+  const readNavigation = function readNavigation({ targetLabel } = {}) {
+    const visible = (el) => el.getClientRects().length > 0 && !el.closest('[aria-hidden="true"]');
+    const primary = document.querySelector('[data-testid="primaryColumn"]') ??
+        document.querySelector("main");
+    const nodes = [
+        ...new Set([
+            ...Array.from(document.querySelectorAll("nav a[href],nav button")).filter((el) => !el.closest("main")),
+            ...Array.from(primary?.querySelectorAll('a[href],button,[role="button"],[role="tab"]') ?? []),
+            ...Array.from(document.querySelectorAll('[role="menu"] a[href], [role="menu"] button, [data-testid="Dropdown"] a[href], [data-testid="Dropdown"] button')),
+        ]),
+    ].filter((el) => visible(el) && !el.closest("article"));
+    const controls = nodes.map((el) => ({
+        role: el.getAttribute("role") || (el.tagName === "A" ? "link" : "button"),
+        label: el.getAttribute("aria-label") || el.innerText.trim(),
+        href: el.getAttribute("href"),
+        selected: el.getAttribute("aria-selected") === "true",
+        disabled: el.disabled === true,
+    }));
+    // Some folder cards are plain clickable text, with no ARIA role or href.
+    // Only the explicitly requested, visible exact label can be promoted to a semantic control.
+    if (targetLabel &&
+        !controls.some((c) => c.label.split("\n")[0] === targetLabel)) {
+        const labels = Array.from(document.querySelectorAll("span,div")).filter((el) => visible(el) &&
+            !el.closest("article") &&
+            el.innerText.trim() === targetLabel &&
+            !Array.from(el.children).some((child) => child.innerText?.trim() === targetLabel));
+        controls.push(...labels.map((el) => ({
+            role: "text",
+            label: el.innerText.trim(),
+            href: null,
+            disabled: false,
+            source: "exact-visible-folder-label",
+        })));
+    }
+    return {
+        page: location.href,
+        controls: controls.slice(0, 40),
+        headings: Array.from(primary?.querySelectorAll('h1,h2,[role="heading"]') ?? [])
+            .filter(visible)
+            .map((el) => el.innerText.trim())
+            .slice(0, 10),
+        needsStateCheck: !controls.length || controls.length > 40,
+        missing: controls.length > 40
+            ? ["navigation-window-overflow"]
+            : controls.length
+                ? []
+                : ["navigation-not-found"],
+    };
+};
+  const readMenu = function readMenu() {
+    const visible = (el) => el.getClientRects().length > 0;
+    const roots = Array.from(document.querySelectorAll('[role="menu"],[role="dialog"],[data-testid="Dropdown"]')).filter(visible);
+    const items = [
+        ...new Set(roots.flatMap((root) => Array.from(root.querySelectorAll('a[href],button,[role="menuitem"]')))),
+    ].filter(visible);
+    return {
+        items: items.map((el) => ({
+            role: el.getAttribute("role") || (el.tagName === "A" ? "link" : "button"),
+            label: el.getAttribute("aria-label") || el.innerText,
+            href: el.getAttribute("href"),
+        })),
+        needsStateCheck: !items.length,
+        missing: items.length ? [] : ["menu-not-found"],
+    };
+};
+  const readXSurface = function readXSurface({ view, posts = [], targetId, replyTargetId, } = {}) {
+    const visible = (el) => el.getClientRects().length > 0;
+    const profile = [...document.querySelectorAll("a[href]")].filter((el) => visible(el) &&
+        ["个人资料", "Profile"].includes(el.getAttribute("aria-label") || el.innerText.trim()) &&
+        /^\/\w{1,15}$/.test(el.getAttribute("href")));
+    const own = profile.length === 1 ? profile[0].getAttribute("href").slice(1) : null;
+    const base = {
+        page: location.href,
+        accountHandle: own,
+        accountURL: own ? `https://x.com/${own}` : null,
+        alerts: [...document.querySelectorAll('[role="alert"]')]
+            .filter(visible)
+            .map((el) => el.innerText),
+    };
+    if (view === "composer") {
+        const dialogs = [
+            ...document.querySelectorAll('[role="dialog"]'),
+        ].filter(visible);
+        const ids = dialogs.length === 1
+            ? [
+                ...new Set([...dialogs[0].querySelectorAll("a[href]")]
+                    .filter(visible)
+                    .flatMap((el) => el
+                    .getAttribute("href")
+                    .match(/^\/\w+\/status\/(\d+)$/)?.[1] ?? [])),
+            ]
+            : [];
+        const replyContexts = [...new Set(dialogs.map((el) => el.innerText))];
+        const replyQuotes = [
+            ...new Set(dialogs.flatMap((el) => [...el.querySelectorAll('[data-testid="tweetText"]')]
+                .filter(visible)
+                .map((text) => text.innerText))),
+        ];
+        return {
+            ...base,
+            replyToId: ids.length === 1 ? ids[0] : null,
+            inlineComposer: dialogs.length === 0,
+            replyContexts,
+            replyQuotes,
+        };
+    }
+    if (view === "posts") {
+        const all = [...document.querySelectorAll("article")].filter(visible);
+        return {
+            ...base,
+            bodies: posts.map((post) => {
+                const articles = all.filter((article) => [...article.querySelectorAll("time")]
+                    .filter(visible)
+                    .find((time) => time.closest("a")?.getAttribute("href") === post.primary)
+                    ?.closest("a")
+                    ?.getAttribute("href") === post.primary);
+                const texts = articles.length === 1
+                    ? [
+                        ...articles[0].querySelectorAll('[data-testid="tweetText"]'),
+                    ].filter((el) => visible(el) && !el.closest?.('[role="link"][tabindex="0"]'))
+                    : [];
+                let replyToId = null, parentEvidence = null;
+                const childIndex = all.indexOf(articles[0]);
+                if (replyTargetId &&
+                    targetId === post.id &&
+                    articles.length === 1 &&
+                    childIndex > 0 &&
+                    new URL(location.href).pathname.endsWith(`/status/${post.id}`)) {
+                    // Nested conversations can include older ancestors before the direct parent.
+                    const parent = [...all[childIndex - 1].querySelectorAll("time")]
+                        .filter(visible)
+                        .find((time) => /^\/\w+\/status\/\d+$/.test(time.closest("a")?.getAttribute("href") ?? ""))
+                        ?.closest("a")
+                        ?.getAttribute("href");
+                    const match = parent?.match(/^\/(\w+)\/status\/(\d+)$/);
+                    const labels = [...articles[0].querySelectorAll("div,span")]
+                        .filter(visible)
+                        .filter((el) => !el.closest('[data-testid="tweetText"]') &&
+                        !el.querySelector('[data-testid="tweetText"]'))
+                        .map((el) => el.innerText.trim().replace(/\s+/g, " "));
+                    const directLabel = match &&
+                        labels.some((text) => [`回复 @${match[1]}`, `Replying to @${match[1]}`].includes(text));
+                    // X can omit the inline reply label on a permalink. Its title still prefixes the direct
+                    // recipient before older ancestors; require that prefix and the adjacent parent together.
+                    const titleRecipient = (document.title ?? "").match(/[“"]@([A-Za-z0-9_]{1,15})(?=\s)/)?.[1];
+                    const titleMatchesParent = match && titleRecipient?.toLowerCase() === match[1].toLowerCase();
+                    if (match?.[2] === replyTargetId &&
+                        (directLabel || titleMatchesParent)) {
+                        replyToId = match[2];
+                        parentEvidence = {
+                            parentPrimary: parent,
+                            childPrimary: post.primary,
+                            labels: labels.filter((text) => /^(回复|Replying to) @/.test(text)),
+                            ...(titleMatchesParent ? { titleRecipient } : {}),
+                        };
+                    }
+                }
+                // Exclude observed nested quote-card text; any remaining ambiguity stays unknown.
+                return {
+                    id: post.id,
+                    body: texts.length === 1
+                        ? (() => {
+                            const root = texts[0];
+                            // innerText adds layout breaks around inline mentions and URLs.
+                            // Reconstruct only observed X permalinks; preserve all other text.
+                            const read = (node) => {
+                                if (node.nodeType === 3)
+                                    return node.textContent ?? "";
+                                if (node.nodeType === 1 &&
+                                    node.tagName === "A") {
+                                    const href = node.getAttribute("href") ?? "";
+                                    if (/^\/\w{1,15}\/status\/\d+$/.test(href))
+                                        return `https://x.com${href}`;
+                                }
+                                return [...node.childNodes].map(read).join("");
+                            };
+                            return root.childNodes ? read(root) : root.innerText;
+                        })()
+                        : null,
+                    replyToId,
+                    parentEvidence,
+                };
+            }),
+        };
+    }
+    return base;
+};
+  const readers = { posts:readPosts, person:readProfile, composer:readComposer, media:readMediaEditor, navigation:readNavigation, menu:readMenu, account:()=>({}) };
+  if (!readers[query.view]) throw new Error('未封装的DOM视图');
+  const raw = readers[query.view](query);
+  const surface = readXSurface({...query, posts:(raw.posts??[]).map(p=>({id:p.id,primary:p.primary}))});
+  return {...raw,...surface,needsStateCheck:Boolean(raw.needsStateCheck)||!surface.accountHandle,
+    ...(query.view==='posts'?{posts:raw.posts.map(p=>({...p,...surface.bodies.find(b=>b.id===p.id)}))}: {})};
+};

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@nextclaw/x-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "X tasks for browser-enabled AI agents: compact results, complete evidence and verified writes.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "x-harness": "./cli/main.js"
+  },
+  "files": [
+    "dist",
+    "generated",
+    "cli",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/skill/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: x-harness
+version: 0.1.1
+description: Use X through task APIs with compact receipts, complete target evidence and verified writes; requires compatible CUA and the user's X login.
+---
+
+# X Harness
+
+Use the root business API. Load only the current task reference; reuse unchanged instructions and a valid binding. Normal use needs no implementation source or type-file reading.
+
+## Bind once
+
+Read current host CUA documentation; bind a real logged-in `tab` or native `app`, exactly one. Preserve other tasks' tabs/editors.
+
+Installed module: `{{MODULE_URL}}`; CLI: `{{CLI_PATH}}`.
+In this repository use the absolute file URL of `<repository>/packages/x-harness/dist/index.js` with original ledger/proof paths. Unresolved placeholders do not require reinstalling an existing repository runtime. Only absent runtime/workspace or an update needs [setup](references/setup.md).
+
+```js
+var { createXGrowthHarness } = await import(moduleURL);
+var x = createXGrowthHarness({ tab, ledgerPath, proofDirectory });
+```
+
+## Load by task
+
+| Current need | Read only |
+| --- | --- |
+| Creator/bookmarks/search/post/person/feedback/account | [reads](references/reads.md) |
+| Publish/reply/follow or a round | [writes](references/writes.md), preamble + common review + matching operation heading |
+| Unknown submission, missing capability or connection failure | [recovery](references/recovery.md) |
+
+Default `receipt` is for status; use `decision` on the first call needing content, `delta` for changed evidence with valid prior context. Keep observations in REPL/proof; return complete relevant evidence and actionable warnings. Never truncate target text or print full DOM/AX. Root calls own capability checks, intent, submission, verification and settlement; verified results need no extra preflight/reload/verify.
+
+Writes require user authorization, verified identity, reviewed evidence and the original ledger plan; project rules own policy. Unknown submission: verify the same action before any new submission. Follow recovery for other failures; read source only to repair a concrete defect/unsupported capability, verify, then return to root calls.

package/skill/references/api.md

@@ -0,0 +1,10 @@
+# API navigation
+
+Compatibility index; normal tasks route directly from the Skill. Load one current reference, not all files.
+
+- Reading: [reads](reads.md).
+- Reviewed writes/rounds: [writes](writes.md), matching operation heading.
+- Failure/unknown submission: [recovery](recovery.md).
+- Missing installation/workspace or update: [setup](setup.md).
+
+Public declarations are the compatibility contract for custom integrations, not a prerequisite for documented calls.

package/skill/references/reads.md

@@ -0,0 +1,23 @@
+# Read tasks
+
+Load for reading only. A valid root binding `x` with existing ledger/proof paths suffices; no write plan needed. `mode` defaults to `receipt`; use `decision` immediately when drafting/reviewing needs text. `delta` omits only unchanged evidence previously returned by this instance; after context loss use `decision`.
+
+| API | Required | Optional |
+| --- | --- | --- |
+| readCreator | handle | target (default 10, 1–50), maxScrolls, navigate, expand, mode |
+| readBookmarks | folder (observed name) | processedIds, limit, maxPages, mode |
+| searchSources | query | processedIds, limit, maxPages, mode |
+| readPost | target: {postId,url,evidenceRef} | mode |
+| readPerson | target: {handle,url,evidenceRef} | mode |
+| readFeedback | targets: [{postId,url,evidenceRef}] | replyLimit, mode |
+| inspectAccount | none | mode |
+| inspectRound | taskId (original batch ID) | none |
+
+```js
+var result = await x.readCreator({ handle: selectedHandle, target: 5, mode: 'decision' });
+var postResult = await x.readPost({ target: observedPost, mode: 'decision' });
+```
+
+Targets/proof come from actual observations, never guessed URLs or made-up references. API owns navigation/expansion and bounded collection. Native creator collection may return `needsCapability`; inspect that signal before changing adapter.
+
+Results include status/evidenceRef/missing/IDs/completeness. In `decision`, creator/bookmark/search use `sources`, post `post`, person `person`, feedback `feedback`; account includes accountHandle/accountURL. `observed` alone does not prove every requested field exists. `pageComplete:false` is a collection boundary, not proof of truncated target text. View media before describing it. Return complete chosen evidence; keep other observations local. Only on failure load recovery.

package/skill/references/recovery.md

@@ -0,0 +1,25 @@
+# Recovery by signal
+
+Load on failure/unknown only. Keep operation/status/missing/code/proof/error; never infer success or repeat identical failures.
+
+| Signal | Next action and exit condition |
+| --- | --- |
+| unknown submission | `await x.verifySubmission({taskId,actionId})`, same IDs; no replacement action or new submission before resolution. |
+| Existing public post needs recovery | `await x.verifyPublishedPost({taskId,draftPath,publicURL,evidenceRef})`; observed URL/proof. Optional sourceLink: {href,resolvedURL,evidenceRef,renderedText?}. |
+| Follow needs independent recovery | `await x.verifyFollow({handle,url,evidenceRef,mode:'decision'})`; honor returned verified. Normal followBatch already verifies. |
+| needsDecision | Resolve returned missing review/proof in original action, resume same ID. Current AI performs internal review under project contract. |
+| waiting | Honor resumeAt/reason, continue independent permitted work; never bypass time/identity/claim gates. |
+| needsCapability | Inspect exact missing method/operation. If a supported binding supplies it, rebind once and retry a necessary read; otherwise repair reported owner with failing sample and targeted validation. |
+| diagnostic.next: inspect-local-proof | Read only `{operation,error}` from diagnostic.evidenceRef; resolve via this reference, keep full proof local. Unknown/intent needs same-ID verification. Unsupported: report code/error and update/support; no private source. |
+| diagnostic.next: restore-proof-store | Restore the workspace's writable proof directory, then resume the same action. Do not replace its ledger or infer submission failure. |
+| Missing fields/partial window | Narrow to target, expand/advance documented bounded window; preserve text. No whole-page output or automatic reload. |
+
+## Host connection or native focus
+
+Failure to list/bind Chrome is a host-connection failure before reaching X, not proof of logged-out X. Per current host documentation rediscover the task tab once; validate navigation plus a necessary visible read. Native focus rejection instead needs latest AX URL/window confirmation and one supported focus correction. Do not repeat discovery or restart editors blindly.
+
+Lost tab: reuse a live owned tab or create a task tab in the same actual browser; preserve other editors. Native fallback changes binding to app, not business calls; unsupported native tasks remain gaps. Network/TUN observations do not authorize setting changes.
+
+## Repair boundary
+
+Normal use/known recovery need no source. Unresolved runtime defect/unsupported capability permits diagnostics: maintainers repair the owner, verify the failed boundary and return to root; consumers report gap/update/support, without private TS. Never scan adapters for arguments, add parsers, bypass refusal or resubmit unknown.