Introducing a new way to review your PRs.

Read the announcement

mvanhorn / last30days-skill

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

View on GitHub

21 documents · Updated Nov 20, 2026

docs / setup-credentials-and-preflight

Setup, credentials, and preflight

Setup and preflight prepare the research engine without hiding what it will need or access. Configuration discovery combines approved local sources with process settings, setup enables optional tools and credentials through a user-led flow, and preflight reports the planned reads, writes, commands, network paths, and credential presence before research begins.

This page focuses on readiness before a run. See Runtime configuration and safety for the wider runtime contract, Health diagnostics and recovery for post-setup checks and repair guidance, and Execution boundaries and HTTP access for the rules that govern subprocess and network work during execution.

Configuration discovery

Configuration discovery builds one runtime view from several sources. Higher-trust and higher-priority sources override lower-priority sources, while project configuration stays inactive until the user explicitly trusts it.

The effective order is:

  1. Process environment variables.
  2. A trusted project file at .claude/last30days.env found from the current directory up to the project boundary.
  3. The global file at ~/…/.env.
  4. macOS Keychain entries in the last30days-<KEY> namespace, or pass(1) entries under the configured last30days/ prefix.

The loader records the winning source for diagnostics. An untrusted project file is not allowed to supply credentials or endpoint settings. In inspection mode, its key names can still be reported so the user knows why a setting had no effect. A process value of LAST30DAYS_TRUST_PROJECT_CONFIG=1 or an equivalent trusted global setting enables the project file; an explicit false process value can deny that trust.

LAST30DAYS_MEMORY_DIR controls the normal report destination. The slash-command wrapper defaults it to ~/Documents/Last30Days, but a bare engine call writes no report file unless it receives this variable or an explicit --save-dir. An explicit --save-dir takes precedence for a run. The configuration loader also carries source, provider, browser, and endpoint settings into the diagnostic view so setup and execution use the same contract. Remote API endpoint settings are read only from the process environment, so a project file cannot silently redirect a run; a configured local corpus keeps the run local instead.

References: skills/…/env.py• L27-40 skills/…/env.py• L91-118 skills/…/env.py• L379-448 skills/…/env.py• L625-650 skills/…/last30days.py• L2911-2943 CONFIGURATION.md• L20-49 CONFIGURATION.md• L97-110

Setup wizard

The setup wizard is a first-run path that makes the main research sources usable without requiring the user to know every credential or command. The host drives the questions and consent; the Python engine performs only the mechanical checks, cookie reads, tool installs, and credential persistence. A server-side setup path performs the same readiness checks without reading browser stores.

The wizard uses SETUP_COMPLETE as its durable completion marker. A missing or empty marker means first run. Once setup writes SETUP_COMPLETE=true, later research skips the onboarding path. Existing process, project, global, Keychain, pass, or host-provided credentials can also show that the user is already configured, so the absence of the global .env file alone does not prove first run.

The user-facing choices have distinct effects:

ChoiceResult
Auto setupOptionally reads browser cookies and best-effort installs or verifies free source tools.
Manual setupLets the user add selected credentials and source settings by hand.
Skip for nowRecords completion and keeps the keyless sources available.

Setup actions are best effort. A missing installer, failed install, or tool outside the agent process PATH is reported as optional coverage loss rather than as a false success. The setup summary distinguishes an active tool from one found on disk but invisible to the process that will run research. It also reports when an approved browser read was blocked by a local permission rule instead of treating the browser as simply empty. Auto setup checks YouTube through yt-dlp, installs or verifies the free Digg, arXiv, and Techmeme command-line sources when their installer path is available, and reports Bright Data status without installing that metered tool. Trustpilot remains opt-in and is not installed during the default setup path.

On an official-only host, an approved browser-cookie scan can be skipped for every supported domain. Setup reports that browser sessions are not read instead of claiming that cookies were found.

References: skills/…/setup_wizard.py• L25-84 skills/…/setup_wizard.py• L95-201 skills/…/setup_wizard.py• L280-368 skills/…/setup_wizard.py• L389-523 skills/…/setup_wizard.py• L712-852 skills/…/setup_wizard.py• L885-940 skills/…/last30days.py• L2994-3052 CONFIGURATION.md• L80-93

Setup conversation

The setup conversation keeps permission decisions visible before a side effect. On hosts with modal prompts it presents the welcome and setup choice first. On other hosts it presents the same sequence as plain dialogue. The sequence is setup choice, browser-cookie consent when needed, optional ScrapeCreators signup, optional source expansion, and then the first research topic.

The setup command cannot ask these questions itself. A host that runs it without first getting consent can trigger browser access without a clear user decision. The host must also relay setup results, including partial installs and authentication outcomes, instead of treating a successful command exit as proof that every source is active.

References: skills/…/SKILL.md• L535-552 skills/…/SKILL.md• L556-640 skills/…/SKILL.md• L644-669 skills/…/setup_wizard.py• L53-67

Server setup

Server setup is a browser-free readiness probe for hosts that cannot use a local desktop session. It checks the tools and configured keys that the server can use, reports the available X method, and can make the same best-effort Digg install as desktop setup. Its JSON result lets the host offer only setup choices that match the server's actual state.

References: skills/…/setup_wizard.py• L885-940

Credential setup

Credentials unlock sources that cannot work from public or keyless access. The system accepts credentials from the process environment and approved local stores, then reports only presence and source status. It does not need to print secret values to explain whether a source can run.

The main credential paths are:

CapabilityCredential or local proofEffect
X searchBrowser session cookies, AUTH_TOKEN plus CT0, XAI_API_KEY, XQUIK_API_KEY, or an API or CLI loginEnables an authenticated X backend.
TikTok, Instagram, and related fallbacksSCRAPECREATORS_API_KEYEnables the selected paid or fallback lanes.
Reasoning and search providersProvider API keys such as XAI_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, or PERPLEXITY_API_KEYMakes the matching provider available.
BlueskyBSKY_HANDLE plus BSKY_APP_PASSWORDEnables authenticated Bluesky access.
GitHubGITHUB_TOKEN or authenticated ghEnables GitHub access without requiring a separate API key.
X API v2 app-only searchX_BEARER_TOKENMakes the X bearer-token path visible in preflight.
Person research lanesDEEPLINE_API_KEYEnables direct profile and post lookup for person-focused research.

Plaintext .env files are expected to use restrictive permissions on POSIX systems. Keychain and pass(1) are lower-priority, additive stores: explicit process or trusted file values still win, and the secret values are read only when a higher-priority source does not provide the key. The remote API pair is different: LAST30DAYS_API_KEY and LAST30DAYS_API_BASE come only from the process environment.

Optional proxy mode uses the local engine while routing only paid provider lanes that have no user key through a metered service. A user's own provider key and every free source remain outside that proxy path. The presence of the remote API pair does not make the run hosted when proxy mode is selected.

The X path uses an ordered backend choice. Browser-cookie credentials take priority when both X cookies and an xAI key exist. The default chain is browser cookies, xAI, the xurl CLI, then Xquik. An explicit LAST30DAYS_X_BACKEND pin is exclusive: if the pinned backend is not available, the system does not silently choose another one. A stored Grok login is opt-in and cannot take over X by itself.

References: skills/…/env.py• L54-78 skills/…/env.py• L760-817 skills/…/env.py• L860-899 skills/…/env.py• L1162-1181 skills/…/proxy.py• L1-18 skills/…/permission_preflight.py• L20-32 skills/…/SKILL.md• L677-710 CONFIGURATION.md• L97-110 CONFIGURATION.md• L265-305 CONFIGURATION.md• L346-364

Browser-cookie setup is an explicit authentication path for logged-in sources. The safe default is no browser read. A normal research run reads cookies only when FROM_BROWSER selects a browser or setup was granted --allow-browser-cookies; --no-browser-cookies hard-disables extraction. Inspection and preflight use plan-only mode and never read cookie values. Setup records the user's consent decision, but it records a browser choice only when that browser actually yields usable cookies.

The cookie flow maps the X domain to AUTH_TOKEN and CT0, and maps the Truth Social domain to its session token. Setup scans Chromium browsers first when consent allows it, then uses Firefox and Safari as fallbacks. Windows supports Firefox extraction; Chromium cookie stores are not treated as supported there. A browser permission error is kept separate from an empty cookie result, and setup reports denied X browser access with the local fix when no other browser supplies a complete pair. Safari access on macOS can require Full Disk Access, so a permission error is surfaced with a one-time retry path rather than hidden. Safari accepts only the requested host or a real subdomain, which prevents a lookalike host from supplying a cookie.

After setup, a single Firefox or Safari winner may be saved as FROM_BROWSER for later runs. Chromium winners are not pinned because doing so can cause a future Keychain prompt. If different services use different browsers, setup leaves the browser choice unpinned. Setup can save the non-secret observation that X cookie access was denied, while cookie values are read for the run and are not saved as browser-cookie data. A later setup run can clear that observation after it succeeds.

References: skills/…/env.py• L657-725 skills/…/env.py• L729-757 skills/…/setup_wizard.py• L64-135 skills/…/setup_wizard.py• L588-641 skills/…/cookie_extract.py• L1-9 skills/…/safari_cookies.py• L94-141 skills/…/safari_cookies.py• L144-208 skills/…/SKILL.md• L580-591 CONFIGURATION.md• L61-62 CONFIGURATION.md• L80-93 CONFIGURATION.md• L200-218

API-key setup

API-key setup gives users a durable way to enable paid or provider-backed sources without placing raw secrets in chat output. The wizard appends only missing keys to the global .env, preserves existing values, and creates the secret file with restrictive permissions. Key values are quoted for reliable reload and are not replaced when the key name already exists unless the user explicitly requests a replacement.

ScrapeCreators can be added through a web signup, a pasted key, or a GitHub device flow. The device flow separates fast start from authorization polling. It validates the short user code before showing it, keeps the private device code out of public output, masks returned API keys, and reports separate outcomes for an already-linked account, a failed profile request, and an upstream profile error after bounded retries. A key is active only after the persistence result confirms that it was saved. The two-command device flow is also available when the user must authorize in a separate step; the single setup --github path remains supported.

References: skills/…/setup_wizard.py• L512-709 skills/…/setup_wizard.py• L859-910 skills/…/setup_wizard.py• L917-1077 skills/…/setup_wizard.py• L1080-1420 skills/…/last30days.py• L3010-3027 skills/…/SKILL.md• L593-615 CONFIGURATION.md• L69-73 CONFIGURATION.md• L97-110

Permission preflight

Permission preflight is a read-only plan of the next research run. It uses safe diagnosis to describe what the engine would read, write, execute, and contact without running research, saving setup or report files, or reading browser-cookie values. The report separates certain writes from conditional writes and marks the run as ready or as needing review.

The report covers:

  • The configuration source and whether project configuration is active or ignored.
  • Browser-cookie mode and candidate browsers without cookie values.
  • Certain and conditional local writes such as the report directory.
  • Credential presence without credential values, including an X bearer token when configured.
  • Optional external commands and whether they are available on PATH.
  • Available sources, native search, and active or ignored endpoint overrides.
  • Action items that need user review, such as an ignored project configuration file, an unsubstituted configuration template, or an unsafe provider endpoint override. A template value is treated as unset until the user replaces it or removes it.

The command supports concise text for people and structured JSON for host tools. The MCP preflight tool exposes the same idea as a read-only, non-destructive operation. It can include a planned MCP save directory so a user can see a possible report write without causing that write. Use --diagnose when full source diagnostics are needed instead of the shorter preflight contract.

References: skills/…/permission_preflight.py• L81-218 skills/…/permission_preflight.py• L225-317 skills/…/pipeline.py• L1786-1880 skills/…/last30days.py• L2952-2968 mcp/…/preflight.go• L14-65 CONFIGURATION.md• L69-70 CONFIGURATION.md• L220-222

Preflight and research start

The command-line entry point selects a safe configuration policy for --preflight, calls diagnosis with safe=True, and renders the permission contract before the research path. Safe diagnosis avoids live checks that could contact a service or prompt for credentials. Browser authentication appears as pending when configuration enables it, so preflight can describe the likely X path without opening a browser store.

For topic quality, the engine also has a separate query preflight. It refuses a known demographic-shopping keyword trap before source retrieval when the topic lacks a hobby, relationship, interest, or budget qualifier. It writes a REFUSE message to standard error and exits with code 2 so the host can ask for context. The user can explicitly bypass this gate, but a safe permission report does not bypass it and does not start research.

The overall start flow is:

flowchart TD
    A[User research request] --> B[Resolve Python 3.12+]
    B -->|missing or invalid| X[Show version error and stop]
    B --> C[Discover configuration]
    C --> D{First run?}
    D -->|yes| E[Ask setup and consent questions]
    E --> F[Run approved setup actions]
    D -->|no| G[Continue with resolved settings]
    F --> G
    G --> H[Run safe permission preflight]
    H --> I{Topic query needs context?}
    I -->|yes| Y[Surface REFUSE and ask for context]
    I -->|no| J[Start research]

References: skills/…/SKILL.md• L421-515 skills/…/SKILL.md• L535-547 skills/…/last30days.py• L25-44 skills/…/last30days.py• L2591-2623 skills/…/last30days.py• L2952-2968 skills/…/preflight.py• L81-119

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the configuration source order aligned across the environment loader, setup completion check, and permission report. A mismatch can make a credential appear active in one surface and absent in another.
  • Keep browser-cookie policy aligned across setup, normal config loading, safe diagnosis, and the host instructions. A change can otherwise cause an unexpected Keychain prompt or make preflight claim that values were read.
  • Keep browser permission-denial results aligned across cookie extraction, setup persistence, and setup status text. A mismatch can turn a blocked browser read into a misleading “no cookies found” result or lose the user's recovery guidance.
  • Keep the setup result states aligned with PATH visibility and source activation. An installed-off-path tool must not be reported as active.
  • Keep the default Printing Press source list aligned across setup installation, source availability, and operator guidance. A source can otherwise be installed but omitted from readiness results or described as available when it is not.
  • Keep API-key persistence and output masking coupled. A new device-auth result must not expose a raw key or claim activation before the write succeeds.
  • Keep the registered provider-key list aligned across environment loading, Keychain and pass(1) lookup, source readiness, and preflight. A newly supported lane can otherwise work in one source but remain invisible to setup or diagnostics.
  • Keep endpoint override trust rules aligned with project-config trust. An ignored project endpoint must remain ignored even when its file contains a valid-looking provider key.
  • Keep the remote API process-only rule aligned with config discovery. A project .env must not gain the ability to redirect research by setting LAST30DAYS_API_BASE and LAST30DAYS_API_KEY.
  • Keep proxy-mode detection aligned with hosted-backend detection. Selecting the metered proxy must not make local research appear to use the remote hosted backend.
  • Keep the report destination contract aligned between the host wrapper and direct engine calls. A documented default must not make a bare engine invocation claim that it writes a file when no save directory is set.
  • Keep the Python version gate and host interpreter selection aligned. A host must not fall back to WebSearch-only output after the engine rejects an unsupported interpreter.
  • Keep permission preflight read-only when adding diagnostics. New checks must not trigger browser reads, live network probes, setup writes, or report writes.

Important failure modes

TriggerConsequenceGuard
Project .claude/last30days.env is not trustedIts credentials and endpoint settings are ignored.Set LAST30DAYS_TRUST_PROJECT_CONFIG=1 from the process environment or trusted global config, then confirm the reported config source.
No save directory is supplied to a bare engine callThe research result can render without a saved report file.Set LAST30DAYS_MEMORY_DIR or pass --save-dir; the per-run flag wins.
FROM_BROWSER is absent, off, or invalidNo browser cookies are read, so cookie-backed X access stays unavailable.Give consent and select a supported browser, or provide AUTH_TOKEN and CT0 or an API key.
A consented browser store denies access during setupSetup cannot verify X cookies and reports browser access as unverified instead of claiming that no cookies exist.Apply the local permission fix shown in setup, then rerun setup or use another supported browser.
Safari cookie access lacks macOS Full Disk AccessSafari fallback cannot authenticate the logged-in source.Grant access to the terminal or host app and retry once; Chrome and Firefox do not use this Safari fix.
A CLI is installed outside the agent process PATHSetup reports it, but the research engine cannot activate it.Add its directory to the agent PATH and restart the agent session or gateway.
Node or npx is unavailable during optional CLI setupDigg, arXiv, or Techmeme remain optional and inactive.Install Node with npx, or run the reported source install command manually.
Bright Data is installed but not logged inThe optional Amazon lane remains inactive.Run brightdata login, then confirm that setup reports the engine as active.
A setup value still contains a configuration templatePreflight treats the value as unset and asks for a real value.Replace the template with a real credential or setting, or remove it.
A provider endpoint override uses an unsafe URLPreflight marks the override as ignored and requires review; the provider does not use it.Use HTTPS, or use HTTP only for a loopback endpoint.
Proxy mode lacks the process API key or base URLPaid lanes that need the proxy stay unavailable instead of becoming hosted.Set both LAST30DAYS_API_KEY and LAST30DAYS_API_BASE, or provide the provider's own key.
A person-focused run lacks DEEPLINE_API_KEYDirect profile and post lookup lanes remain unavailable.Provide the key through the process environment or an approved local credential store.
GitHub device authorization succeeds but the ScrapeCreators profile request failsSetup reports the actual profile or upstream error, and no paid source becomes active.Retry after the reported service or network issue is resolved; do not treat authorization alone as a usable API key.
ScrapeCreators authorization succeeds but key persistence failsSignup succeeded, but the paid sources are not active.Treat persisted: false as inactive and save the key manually before retrying.
Python is below 3.12 or the override points to an older interpreterThe engine exits before setup or research.Install Python 3.12+ or set LAST30DAYS_PYTHON to a supported interpreter.
A topic matches the Class 1 shopping trap without a qualifierThe engine refuses before retrieval and asks for useful context.Add an interest, relationship, or budget, then rerun the enriched topic.

Key files

FileWhy to read it
skills/…/env.pyDefines configuration discovery, trust boundaries, credential sources, proxy mode, and browser-cookie policy.
skills/…/setup_wizard.pyDefines first-run setup, server readiness checks, source-tool status, secret-safe writes, and device authorization outcomes.
skills/…/safari_cookies.pyShows the macOS Safari cookie boundary and how access or host-match failures are surfaced.
skills/…/permission_preflight.pyDefines the secret-free permission report, endpoint override checks, and its text form.
skills/…/proxy.pyDefines the optional metered path for paid provider calls that have no user key.
skills/…/pipeline.pyConnects safe diagnosis to source availability and the permission contract.
skills/…/last30days.pyCoordinates interpreter checks, configuration policy, setup dispatch, and preflight output.
skills/…/preflight.pyDefines the separate query-quality refusal gate that runs before source retrieval.
skills/…/SKILL.mdDefines the host-driven setup conversation, consent rules, and runtime preflight sequence.
CONFIGURATION.mdGives the operator-facing contract for config locations, credential options, setup behavior, and safe preflight commands.
mcp/…/preflight.goExposes the safe preflight plan to MCP clients without running research.