Ascent Research

ascent-research — Full CLI Skill

Build reproducible, figure-rich research reports with a persistent per-session wiki. One CLI, three input modes (HTTP API / browser fallback / local file tree), three output surfaces (narrative report / entity wiki / event log), autonomous loop optional.

Installation (MANDATORY — run before any playbook)

Three binaries must be on PATH: ascent-research (the CLI itself), postagent (HTTP ingest — npm), actionbook (browser fallback — npm).

# 1. The ascent-research CLI (Rust). `autoresearch` is a default feature
#    so `loop` works out of the box; add LLM providers for loop/wiki/bilingual.
cargo install ascent-research --features "provider-claude provider-codex"
# or, including the third-party OpenCode Go subscription provider (v0.4.2+):
# cargo install ascent-research --features "provider-claude provider-codex provider-opencode-go"

# 2. Node.js dependency tools
npm install -g postagent @actionbookdev/cli

Doctor check — run this FIRST in every new session:

ascent-research --json doctor || { echo "INSTALL_REQUIRED"; exit 1; }

If the doctor check exits non-zero, STOP and run the install block above. Do NOT narrate the workflow in chat as a substitute — the CLI is the only thing that actually produces report.html.

For any playbook that will fetch online sources through add, batch, or route, run tool smoke as well:

ascent-research --json doctor --tool-smoke

If a required tool-smoke check fails, STOP and surface the failing tool check. Optional warnings such as postagent_public_dry_run should be treated as routing guidance: prefer browser or local ingest if public postagent fetches are not accepted by the installed postagent contract.

When online hands fail, preserve fallback provenance instead of silently switching tools. If you cache a web page/source note locally, ingest it with:

ascent-research add-local ./cache --slug <slug> \
  --original-url https://example.com/source \
  --origin-tool curl \
  --origin-note "actionbook daemon unavailable; cached with curl"

Rules for fallback sources:

• Use source notes only as a last resort when postagent/browser cannot fetch.
• Every source note must list the original URLs and explain why direct ingest failed.
• In the final reply, disclose which hand failed and which fallback path was used.
• For legal, medical, financial, current, or compliance claims, do not present a source note as high-confidence primary evidence unless the report labels the conclusion limited-confidence or later re-fetches the original URLs.

For any playbook that will call loop, wiki query, or synthesize --bilingual, also run a live provider smoke check first:

ascent-research --json doctor --provider-smoke --provider codex
# or, if you explicitly want Claude:
ascent-research --json doctor --provider-smoke --provider claude

If provider smoke fails, STOP and surface the failing provider check. Do not start the research loop or bilingual synthesis until the provider is healthy.

Data home: all sessions, user preset overrides, wiki pages, and rendered reports live under ~/.actionbook/ascent-research/. Override with ACTIONBOOK_RESEARCH_HOME for sandboxing. Upgraders from v0.2: the legacy ~/.actionbook/research/ tree is read-only — new writes land in the v0.3 canonical root.

V2 Browser Backend Setup (one-time, REQUIRED for add/batch on JS pages)

ascent-research defaults to the V2 actionbook MCP backend (ACTIONBOOK_BACKEND=v2-mcp). Four things must be set up once — without all four, every browser-based fetch will fail.

1. Actionbook Chrome extension + dedicated profile (recommended)

Install Actionbook Cloud (v2) in Chrome, v0.2.0-alpha.4 or later.

Strongly recommend a dedicated Chrome profile, for two reasons:

• chrome.debugger conflict: if actionbook shares a profile with a password manager / AI sidebar / translation extension that injects content frames into every page, Chrome will refuse to attach with Cannot access a chrome-extension:// URL of different extension, and every V2 attach call fails.
• Cookie scoping per profile: fetching logged-in content (X / GitHub private / SaaS dashboards) requires actionbook to be in the same profile that is logged in. A mixed-profile setup = unlogged-in fetches.

How to set up: Chrome top-right avatar → Add → new profile named "Actionbook Research" → install only actionbook in this profile → log into every research-target site here. macOS one-shot launcher:

open -na "Google Chrome" --args --profile-directory="Profile X"

If a user reports "V2 doesn't fetch / always EXTENSION_OFFLINE / always attach fails", your first question is whether the profile is dedicated.

2. ACTIONBOOK_API_KEY permanent export

# Generate an ak_* token at https://actionbook.dev/dashboard/api-keys, then:
echo 'export ACTIONBOOK_API_KEY=ak_xxxxxxxxxxxxxxxx' > ~/.actionbook.env
chmod 600 ~/.actionbook.env
echo '[ -f ~/.actionbook.env ] && source ~/.actionbook.env' >> ~/.zshrc  # or .bashrc

⚠️ Never paste the token into chat / IDE prompt / git commit. ascent-research never echoes the token in stderr / logs.

3. Claude Code permission allow rule

Claude Code's default classifier blocks certain "advanced" actionbook patterns (XHR interception / screenshot return / sensitive cookie probes), even when these are explicitly recommended by actionbook's official manuals. One settings rule whitelists the whole MCP tool permanently:

// ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "mcp__*__actionbook"  // allow all actionbook MCP tool calls
    ]
  }
}

Whitelist actionbook narrowly; other tools (reading Chrome profile, calling arbitrary external APIs) remain protected by the classifier. Do not use --dangerously-skip-permissions to bypass globally.

4. postagent secrets — one-time register per site

postagent does not read shell env / gh CLI / macOS Keychain — it has its own secret store:

postagent auth github        # GitHub PAT (the tech preset routes GitHub URLs through the API by default)
postagent auth x             # X (if you want the X API instead of V2 scraping the timeline)
postagent auth openai        # OpenAI / Anthropic / etc.
postagent auth status        # verify all stored

Without a GitHub token, every github.com/<owner>/<repo> URL in the tech preset hits unauthenticated GitHub API and will almost certainly hit rate-limit 403.

When to use V2 vs postagent vs add-local

Research target
   │
   ├── Public API (api.github.com / api.openai.com / etc.)
   │   → preset auto-routes to postagent → fast (< 500ms)
   │   Requires: postagent auth configured (step 4 above)
   │
   ├── Static / semi-static page (official blog / docs / changelog)
   │   → preset fallback routes to V2 browser → ~3-5s
   │   Requires: dedicated profile + actionbook online
   │
   ├── Heavy SPA + public content (HN / Reddit feed / x.com timeline)
   │   → from inside Claude Code, call the actionbook MCP tool directly
   │     (Claude writes its own run-code script + controls timeout)
   │   → write captured content to local .md files
   │   → `ascent-research add-local <dir>` injects them into the session
   │   Requires: step 3 allow rule (otherwise classifier blocks XHR interception)
   │
   └── Login-required SaaS (Linear / Notion / GitHub private repo)
       → same as above, AND the actionbook profile must be logged into that site
       → cannot use postagent (no public API token, or too expensive)

Pitfalls to avoid

• document.cookie is not a reliable login check. X, GitHub, and most SaaS set their session token (e.g. X's auth_token, GitHub's user_session) as HttpOnly cookies — JavaScript cannot read them. To verify "is the user logged in", issue a request to an authenticated endpoint and check status 200 vs 401, do not grep document.cookie.
• Don't expect 3 s networkidle on heavy SPAs. GitHub PR pages and x.com search results take 5-10 s to hydrate. The V2 inline JS now uses a three-stage wait (DOMContentLoaded + networkidle + body-content poll, ~16 s worst case) to handle this; if you write a custom run-code for an even heavier site, mirror the same pattern.
• add-local accepts UTF-8 text now (including dense CJK / Japanese / Korean / emoji). Pre-2026-05-17 the text detector mis-flagged these as binary; that's fixed in this build.
• GitHub PR / repo URLs route through postagent, not V2 browser — if postagent auth github is not configured, you'll get fetch_failed even though V2 looks healthy. Step 4 above prevents this.
• x.com / twitter.com URLs use a dedicated XTweet runcode flavor since v0.4.1. The generic networkidle + body-text poll returned only X's left-nav chrome (~160 bytes) because X's tweet <article> is GraphQL-hydrated AFTER networkidle, and the page virtualizes (unmounts scrolled-off articles). XTweet uses waitForSelector('article[data-testid="tweet"]', …) instead, plus snapshot-collect across scrolls keyed by tweetId so the main tweet survives virtualization. Thread + media (tweet attach
  • link card + video poster) are returned as markdown ![](url) so rich-html renders them as <img> and Obsidian / VS Code preview shows them. Three explicit preset rules — x-tweet-status (3-seg path), x-search-live (/search), x-profile (1-seg) — route through this flavor; everything else x.com routes via fallback (also XTweet by host sniff).
• Default --min-bytes is 500 — short single tweets need --min-bytes 200. A typical single tweet returns ~400-500 bytes (text + author + metrics); multi-article threads naturally exceed 500. If a known-good single X URL gets SMELL_REJECTED reject_reason=empty_content, pass --min-bytes 200. Future spec may auto-adjust per x-tweet-status kind.

Mandatory Tail (MANDATORY — finish is preferred)

ascent-research loop does NOT render report.html. Before you declare the task done, prefer the single completion protocol:

ascent-research finish <slug> [--bilingual] [--open]

finish runs coverage -> synthesize -> audit and returns non-zero unless all three stages pass. If you need to debug a stage, run the inspection commands individually:

ascent-research coverage <slug>
ascent-research synthesize <slug> [--bilingual] [--open]
ascent-research --json audit <slug>

Rules:

• Always run finish after loop (or after manual add / write work) before replying.
• If the user asks for Chinese, bilingual output, or 中英文 output, you MUST run finish <slug> --bilingual; plain finish renders English-only HTML.
• If finish fails at coverage, do NOT claim the report is complete. Surface the blockers from report_ready_blockers and keep working or ask the user what to relax.
• If finish fails at synthesize, do NOT claim report.html exists. Surface the synthesize error and keep working or ask the user what to relax.
• If finish fails at audit, do NOT claim the session is验收-complete. Surface audit_blockers and keep working or ask the user what to relax.
• If --bilingual reports bilingual_skipped, do NOT claim Chinese output is complete. Fix the provider and rerun finish <slug> --bilingual.
• In the final reply, include the exact <session>/report.html path and audit_status.

Chinese/bilingual generation:

# Default translator is Claude when built with provider-claude.
ascent-research finish <slug> --bilingual --open

# If Claude auth/API key is unavailable but the binary was built with provider-codex:
ASR_BILINGUAL_PROVIDER=codex ascent-research finish <slug> --bilingual --open

--bilingual produces an English/中文 toggle in report.html by injecting <p class="tr-zh"> siblings. Without --bilingual, the report intentionally has no Chinese paragraphs.

Dynamic Fact Topics Require Fact Check

For live, sports, news, current roster, current price, latest version, market, legal, medical, financial, or other time-sensitive factual research, create the session with --tag fact-check.

ascent-research new "<topic>" --slug <slug> --preset tech --tag fact-check

For sports/current-roster tasks, prefer the sports preset and seed at least one roster source URL from an official roster page, Basketball-Reference team season page, or ESPN roster page before synthesis:

ascent-research new "<topic>" --slug <slug> --preset sports --tag fact-check
ascent-research add "https://www.nba.com/<team>/roster" --slug <slug>
ascent-research add "https://www.basketball-reference.com/teams/<TEAM>/<YEAR>.html" --slug <slug>

When --tag fact-check is present, the loop must emit fact_check actions for concrete person, team, date, number, price, roster, standing, release version, or current-status claims before the final report depends on them. If evidence is stale or conflicting, emit fact_check with outcome:"uncertain" and continue fetching instead of writing a confident assertion.

Before final synthesis on these sessions, run:

ascent-research coverage <slug> --json

Verify fact_check_required=true and fact_checks_total >= 1. If report_ready_blockers contains fact_checks_total or fact_check_invalid_sources, do NOT run synthesize; continue fetching accepted sources and emitting fact_check actions.

GitHub Trust / Fake-Star Audit

For “fake GitHub stars”, repository trust, suspicious star growth, or investor/developer due diligence tasks, start with the deterministic audit hand before asking the LLM to interpret anything. Do not ask the model to decide whether stars are fake from vibes.

ascent-research github-audit <owner>/<repo> --depth timeline --sample 500 --out audit.json --html audit.html
ascent-research new "<owner>/<repo> GitHub trust audit" --slug <owner>-<repo>-trust --preset github-trust --tag fact-check
ascent-research add-local audit.json --slug <owner>-<repo>-trust
ascent-research loop <owner>-<repo>-trust --provider codex --iterations 8
ascent-research finish <owner>-<repo>-trust --open

Rules:

• github-audit outputs trust score, risk score, band, confidence, reasons, and evidence; never call a repo “fake” or “real” deterministically.
• If the user asks whether a repo looks trustworthy, show audit.html first. It is the deterministic scorecard: trust score, risk score, confidence, metric dashboard, reasons, and evidence gaps.
• Use --depth repo for anonymous quick checks; use stargazers or timeline only when postagent can resolve $POSTAGENT.GITHUB.TOKEN.
• The audit JSON is the evidence artifact. Add it with add-local before loop so the report cites the deterministic signals instead of re-deriving them.
• --preset github-trust is for contextual follow-up sources; it does not replace github-audit scoring.
• Finish still goes through the normal completion protocol: coverage -> synthesize -> audit.

Mental Model

One research project = one session under ~/.actionbook/ascent-research/<slug>/

  session.toml     metadata (topic, preset, tags, parent slug)
  SCHEMA.md        user-editable loop guidance
  session.md       narrative — Overview / 01·WHY / 02·HOW / ... report spine
  session.jsonl    append-only event log — authoritative machine state
  raw/             every accepted source, one file
  wiki/<slug>.md   persistent entity + concept + analysis pages
  diagrams/*.svg   hand-drawn figures, inlined in the HTML report
  report.html      rendered editorial output with wiki TOC + bilingual toggle

Three-layer control flow:

LLM orchestrator (this skill / active-research / custom agent)
      |  [CLI ONLY — observability > terseness]
      v
research CLI  ──>  route presets  ──>  postagent (HTTP)
                                   ──>  actionbook browser (CDP)
                                   ──>  local file reader (file://)
      |  [infra-enforced smell test on every fetched body]
      v
session.md + session.jsonl + wiki/ + diagrams/ + report.html

Everything downstream of the CLI is stateless between turns — the agent addresses state only by --slug. The CLI holds the event log and the preset registry.

Command Surface (all of it)

Session lifecycle

ascent-research new <topic>     --slug <s> [--preset tech] [--tag t]... [--from <parent>] [--force]
ascent-research list            [--tag t] [--tree]
ascent-research show <slug>
ascent-research status          [<slug>]
ascent-research resume <slug>
ascent-research close           [<slug>]
ascent-research rm <slug>       [--force]

• new seeds SCHEMA.md with a starter template and sets the session active.
• --from <parent> forks a session — parent's Overview becomes the new Context, tags are inherited. Wiki does NOT auto-fork (by design).
• --force on new overwrites an existing slug; on rm skips the dry-run confirmation.
• list --tree renders parent→child hierarchy as ASCII.

Ingest — online

ascent-research add <url>       [--slug <s>] [--timeout <ms>] [--readable | --no-readable]
                          [--min-bytes N] [--on-short-body {reject|warn}]
                          [--frame-id <u32>] [--run-code-args <json>] [--reseed]
                          [--actionbook-backend {v2-mcp|v1-cli}]
ascent-research batch <url>...  [--slug <s>] [--concurrency 1..16] [--timeout <ms>] [--readable | --no-readable]
                          [--frame-id <u32>] [--run-code-args <json>] [--reseed]
                          [--actionbook-backend {v2-mcp|v1-cli}]
ascent-research sources         [<slug>] [--rejected]
ascent-research route <url>     [--rules <file>] [--preset <name>] [--prefer browser]

• add routes via preset (tech.toml default) — HN/arXiv/GitHub hit postagent directly, other hosts fall through to actionbook browser.
• Default per-source timeout is 90 s since v0.4.0 (V2 server inner run-code default is 60 s; the extra 30 s covers edge + transport overhead). Override with --timeout <ms>.
• --frame-id targets a specific iframe for V2 run-code. --run-code-args injects structured JSON arguments into the script.
• --reseed re-probes the V2 catalog even when a wiki entry already exists (the default pre-fetch step skips already-seeded sites).
• --actionbook-backend v1-cli forces the legacy subprocess path for this single call (useful when the V2 extension is offline). Otherwise the binary-wide default (env ACTIONBOOK_BACKEND, default v2-mcp) applies.
• batch fetches in parallel workers; each call runs the smell test independently.
• route prints the decision without fetching — useful for debugging preset rules.
• Smell test fails → SMELL_REJECTED with a reason (too_short, wrong_url, browser_chrome_error, etc.). The URL attempt is always logged in jsonl.
• A composite route rule (one rule, N parts merged under composite-v1 schema) is a single source; if any part rejects, the source is rejected and composite_failed_part in the jsonl event names the failing label.

Ingest — local (v3)

ascent-research add-local <path> [--slug <s>] [--glob '...']... [--max-file-bytes N] [--max-total-bytes N]
                          [--original-url URL] [--origin-tool TOOL] [--origin-note TEXT]

• <path> can be file://abs/path, /abs/path, ./rel/path, ~/rel/path, or a bare path.
• --glob is repeatable; prefix ! excludes. Default glob matches all files.
• Caps enforced at walk time: default 256 KB per file, 2 MB per walk. Direct add file:///… calls get an 8 MB fetch-stage backstop.
• Binary files (null-byte probe) are rejected; only text survives the gate.
• Each accepted file becomes an independent source with file:// URL — same pipeline as online add, goes through smell test, appears in sources and coverage.
• --original-url / --origin-tool / --origin-note record fallback provenance in session.jsonl when a local file is standing in for a failed online hand.

GitHub trust audit

ascent-research github-audit <owner>/<repo> [--depth repo|stargazers|timeline] [--sample N] [--out audit.json] [--html audit.html]
ascent-research github-audit https://github.com/<owner>/<repo> --depth timeline --sample 500 --out audit.json --html audit.html

• Produces a deterministic trust evidence envelope: repo ratios, sampled stargazer profile signals, timeline burst signals, trust score, risk score/band/confidence/reasons/evidence.
• Default depth is stargazers, default sample is 200. Use repo when GitHub token auth is unavailable.
• stargazers and timeline use postagent with Authorization: Bearer $POSTAGENT.GITHUB.TOKEN; no raw token should appear in stdout/stderr/session files.
• --out writes the full JSON envelope for add-local ingestion into a follow-up --preset github-trust report.
• --html writes the deterministic scorecard HTML. This is not the generic research report template and does not call an LLM.