@nextclaw/x-harness 0.0.0-stage → 0.1.0

package/generated/observation.mjs

@@ -0,0 +1,514 @@
+// 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.0",
+  "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,52 @@
+---
+name: x-harness
+version: 0.1.0
+description: Use X through named task APIs with compact receipts, complete target evidence and verified writes. Requires a compatible CUA browser host and the user's own logged-in X account. Install and update with the npm-distributed X Harness runtime.
+---
+
+# X Harness
+
+Use the installed runtime; normal tasks call its root business API. Do not recreate browser selectors, print full DOM/AX, or call lower layers for normal work. Keep observations local and only return the relevant complete evidence, receipt and actionable warnings.
+
+## First use
+
+Installed module: `{{MODULE_URL}}`
+CLI: `{{CLI_PATH}}`
+
+If these placeholders are unresolved, install first:
+`npx @nextclaw/x-harness@latest setup --target codex` (or `--target claude`).
+
+Requires Node 22+, a host that exposes compatible CUA `tab` or native `app` methods, and the user's own X login. Codex desktop CUA is validated. Installing this Skill into Claude only installs instructions; confirm that host's browser methods before claiming it can execute. If browser access/login is absent, report the actual missing condition; never fabricate execution or borrow the publisher's account.
+
+Read the host's CUA documentation before using its controls. Bind/create a task tab through the host's documented API, preserving the user's session. A compatible tab has `url()`, `playwright.evaluate()`, locator methods and optional navigation/AX/screenshot methods; native apps have `getAXState()`, click/key/paste methods. Use the provided connection; do not launch an unrelated automation driver.
+
+Initialize the user's own workspace once with `node <CLI> init --directory <user workspace> --account <user handle>`. It returns `ledgerPath`, `proofDirectory`, `taskId` and account. Existing project configurations and ledgers remain the owner; reuse those instead of creating duplicate state. Never import the publisher's operations directories, policies or credentials.
+
+In the host's Node-capable REPL:
+
+```js
+const { createXGrowthHarness } = await import("MODULE_URL_FROM_SETUP");
+const x = createXGrowthHarness({ tab, ledgerPath, proofDirectory });
+const result = await x.readCreator({
+  handle: "USER_HANDLE",
+  target: 5,
+  mode: "decision",
+});
+// Print only the needed result; keep the full browser observation in the REPL.
+```
+
+Substitute the stable installed URL and initialized paths. Never assume an old imported module hot-reloads after updating. Read `references/api.md` only for the next operation's arguments and the installed `.d.ts` for detailed types.
+
+## Execution
+
+Choose the single named task: readCreator/readBookmarks/searchSources/readPost/readPerson/readFeedback/inspectAccount; publishPost/replyToPost/followOne/followBatch; inspectRound/runGrowthRound; verifySubmission/verifyPublishedPost/verifyFollow. `receipt` is the default compact result; `decision` includes full relevant evidence; `delta` rereads and returns changed complete evidence plus unchanged IDs. Do not trim the target's body to save tokens.
+
+Writing needs explicit authorization from the current user, verified identity, their own ledger plan, reviewed prepared actions and existing evidence files. Initialization plans zero writes. Set the authorized planned count in the original ledger before execution; never expand an authorized scope yourself. Check the installed types for action, quality and executor fields; retain one owner for the ledger, do not invent approvals or evidence. The current runtime writes only 07:00–22:00 Asia/Shanghai and follow candidate gates require reviewed Chinese-language, blue-check candidates; disclose these conditions when relevant.
+
+Interpret returned status literally: `verified` requires public proof; `unknown` is not success. For an unknown submission, call verifySubmission on the same action before any new submission. `needsCapability`, `needsDecision`, `waiting` and partial windows must be reported, with the next required condition. Capture visual media before making claims about its contents.
+
+## Updates
+
+Run `npx @nextclaw/x-harness@latest update --target codex` (or claude). It stages the exact fetched release, replaces only managed runtime/Skill directories, saves the previous version and retains user workspaces/configurations. It refuses unfamiliar directories. Start a fresh module binding afterward and verify the next real read operation. A release's distributed Skill and runtime use the same version.
+
+Free use under the bundled proprietary license; the distributed JS is readable, the TS source repository remains private. Website: https://x-harness.gemigo.app/

package/skill/references/api.md

@@ -0,0 +1,37 @@
+# Root API usage
+
+Bind once: `createXGrowthHarness({ tab, ledgerPath, proofDirectory })`. Exactly one `tab` or native `app`. Read operations can use the initialized zero-write plan.
+
+```js
+await x.readCreator({
+  handle: "USER_HANDLE",
+  target: 10,
+  maxScrolls: 8,
+  mode: "decision",
+});
+await x.searchSources({ query: "AI agents", limit: 5, mode: "decision" });
+await x.readBookmarks({ folder: "FOLDER_NAME", limit: 5, mode: "decision" });
+await x.inspectAccount({ mode: "decision" });
+await x.readPost({ target: { postId, url, evidenceRef }, mode: "decision" });
+await x.readPerson({ target: { handle, url, evidenceRef }, mode: "decision" });
+await x.readFeedback({
+  targets: [{ postId, url, evidenceRef }],
+  mode: "decision",
+});
+await x.inspectRound({ taskId });
+```
+
+Targets/evidence come from prior observed results. Exact option types are in the installed `dist/types.d.ts`. `readFeedback` may need your accountURL as documented there. Preserve full relevant content and expose missing fields rather than inventing them.
+
+```js
+await x.publishPost({ taskId, draftPath, preparedAction: originalAction });
+await x.replyToPost({ taskId, postId, text, preparedAction: replyAction });
+await x.followOne({ taskId, handle }); // action already prepared in the original ledger
+await x.followBatch({ taskId, handles, preparedActions });
+await x.verifySubmission({ taskId, actionId });
+await x.verifyPublishedPost({ taskId, draftPath, publicURL, evidenceRef });
+await x.verifyFollow({ handle, url, evidenceRef });
+await x.runGrowthRound({ taskId, maxActions: 3 });
+```
+
+Before preparing writes, read the appropriate installed PreparedAction and operation option types. Required reviewed evidence cannot be replaced with a made-up reference. Original posts include actual draftPath, complete text, observed compose URL/proof, author proof and approvedText/draftFingerprint quality. Reply/follow targets require observed evidence. Concurrent task tabs need an explicitly evidenced executor scope; see HarnessOptions/Executor. Business root calls own capability checks, intent journaling, single submission, public verification and ledger settlement.