# Quickstart

> First /last30days invocation, first-run setup wizard signals, saved output location, and --diagnose verification.

- Repository: mvanhorn/last30days-skill
- GitHub: https://github.com/mvanhorn/last30days-skill
- Human docs: https://grok-wiki.com/public/docs/mvanhorn-last30days-skill-50b5421a8cca
- Complete Markdown: https://grok-wiki.com/public/docs/mvanhorn-last30days-skill-50b5421a8cca/llms-full.txt

## Source Files

- `skills/last30days/SKILL.md`
- `skills/last30days/scripts/lib/setup_wizard.py`
- `skills/last30days/scripts/last30days.py`
- `CONFIGURATION.md`
- `README.md`

---

---
title: "Quickstart"
description: "First /last30days invocation, first-run setup wizard signals, saved output location, and --diagnose verification."
---

The `/last30days` slash command loads `skills/last30days/SKILL.md`, runs Python 3.12+ preflight, optionally executes Step 0 first-run setup, then invokes `scripts/last30days.py` with `--emit=compact` and `--save-dir` pointed at `LAST30DAYS_MEMORY_DIR` (default `~/Documents/Last30Days/`). Reddit, Hacker News, Polymarket, and GitHub (when `gh` is installed) work with no API keys on the first run.

## Prerequisites

| Requirement | Detail |
|---|---|
| Skill installed | Claude Code marketplace, `npx skills add`, Hermes, or another Agent Skills host — see [Installation](/installation) |
| Python | 3.12+ (`python3.12`, `python3.13`, or `python3.14`); the skill resolves `LAST30DAYS_PYTHON` before any engine call |
| Optional keys | None required for the zero-config sources above |

<Note>
The product path is the slash command in your harness. Direct CLI (`python3 …/last30days.py`) is for scripting, cron, and verification — not a substitute for `/last30days` in chat.
</Note>

## First invocation

<Steps>
<Step title="Install the skill">
Install once per machine (marketplace plugin or `npx skills add mvanhorn/last30days-skill -g`). Re-run install or update when syncing a dev checkout.
</Step>
<Step title="Run a topic">
In Claude Code, Codex, Cursor, Gemini CLI, or any host that exposes the skill:

```
/last30days OpenClaw
```

The hosting model reads `SKILL.md`, parses intent (GENERAL by default), builds `ACTIVE_SOURCES_LIST` from your config, and prints a one-line confirmation such as:

```
/last30days - searching Reddit, Hacker News, Polymarket, and GitHub for what people are saying about OpenClaw.
```

It then runs pre-research (when WebSearch is available), plans sub-queries, and calls the engine with `--emit=compact --save-dir="${LAST30DAYS_MEMORY_DIR}" --save-suffix=v3`.
</Step>
<Step title="Read the response">
Valid output starts with the engine badge (`🌐 last30days v{VERSION} · synced {YYYY-MM-DD}`), then `What I learned:` (or the comparison title for `vs` topics), KEY PATTERNS, the pass-through emoji-tree footer, and an invitation — no trailing `Sources:` block.
</Step>
</Steps>

```mermaid
sequenceDiagram
  participant User
  participant Harness as Agent harness
  participant Skill as SKILL.md contract
  participant Engine as last30days.py

  User->>Harness: /last30days topic
  Harness->>Skill: Read + Step 0 check
  alt First run
    Skill->>Harness: Setup wizard (nux-wizard flow)
    Harness->>Engine: optional setup subcommand
  end
  Harness->>Engine: --emit=compact --save-dir=MEMORY_DIR
  Engine-->>Harness: compact stdout + footer save path
  Harness-->>User: Synthesis + saved raw path
```

## First-run setup wizard

Setup splits into **detection** (Python), **UI** (hosting model via `SKILL.md`), and **auto-actions** (engine `setup` subcommand).

### Detection signals

| Signal | Meaning |
|---|---|
| `~/.config/last30days/.env` missing | Treated as first run (`SKILL.md` Step 0) |
| `SETUP_COMPLETE` absent or empty in config | `setup_wizard.is_first_run()` returns true |
| `SETUP_COMPLETE=true` present | Step 0 skipped silently — no setup banner on every run |

Config merge order: process environment → `.claude/last30days.env` (walked up from cwd) → `~/.config/last30days/.env` (override with `LAST30DAYS_CONFIG_DIR`).

### What the hosting model does (Step 0)

On first run the agent must:

1. Read `skills/last30days/nux-wizard.md` (relative to the skill root) and follow platform-specific flow (Claude Code vs OpenClaw, ScrapeCreators opt-in, topic picker).
2. After setup, ensure `SETUP_COMPLETE=true` is written to `~/.config/last30days/.env`.
3. Proceed to intent parsing and research without repeating setup on later runs.

<Warning>
`nux-wizard.md` is referenced in `SKILL.md` Step 0 as the wizard script. If that file is missing from your install tree, first-run UX falls back to manual configuration — use the engine `setup` subcommand and [Configure sources](/configure-sources) instead.
</Warning>

### Engine auto-setup (`setup` subcommand)

The model or you can run auto-setup directly (dev/fallback path):

```bash
# From the directory that contains scripts/last30days.py
python3 scripts/last30days.py setup
```

`run_auto_setup()` then:

- Extracts browser cookies for registered domains (X/Twitter and related cookie-jar sources) via `FROM_BROWSER=auto`
- Checks `yt-dlp`; on macOS with Homebrew, may run `brew install yt-dlp`
- Writes `SETUP_COMPLETE=true` and `FROM_BROWSER={browser}` to `~/.config/last30days/.env` (append-only, no overwrite of existing keys)

Optional flags after `setup` (parsed as extra argv): `--openclaw`, `--github`, `--device-auth` for platform-specific auth flows.

### Status text you should recognize

stderr/stdout from `setup` ends with a summary from `get_setup_status_text()`, for example:

<RequestExample>

```text
Setup complete! Here's what I found:

  - X cookies found in chrome
  - yt-dlp already installed

Configuration saved. Future runs will auto-detect your browsers.
```

</RequestExample>

Other branches include `No browser cookies found for X/Twitter`, `Installed yt-dlp via Homebrew`, `yt-dlp install failed — run brew install yt-dlp manually`, and `yt-dlp not found. Install Homebrew first…`.

<Info>
README describes “run it once and the setup wizard unlocks X, YouTube, TikTok, and more in 30 seconds” — that unlock is cookie extraction + `yt-dlp` plus optional ScrapeCreators keys, not a separate product install.
</Info>

## Where output is saved

| Artifact | Path pattern | When |
|---|---|---|
| Raw research dump | `{LAST30DAYS_MEMORY_DIR}/{slug}-raw[-suffix].md` | Every agent-mode run (`--save-suffix=v3` in `SKILL.md`) |
| Same-day collision | `{slug}-raw[-suffix]-{YYYY-MM-DD}.md` | If the target file already exists |
| HTML brief (optional) | `{LAST30DAYS_MEMORY_DIR}/{slug}-brief.html` | User asks for shareable HTML |
| Engine pointer | Footer line `📎 Raw results saved to …` | Confirms resolved path in chat |

<ParamField body="LAST30DAYS_MEMORY_DIR" type="string">
Default `~/Documents/Last30Days/` on Linux/macOS; `C:\Users\<you>\Documents\Last30Days\` on Windows. Set before invoking the skill to redirect all saves.
</ParamField>

<ParamField body="--save-dir" type="path">
Per-run override passed by the skill or CLI. Creates the directory if needed.
</ParamField>

<ParamField body="--save-suffix" type="string">
Distinguishes parallel runs of the same topic (e.g. `v3`, client slug).
</ParamField>

Slug rules: topic lowercased, non-alphanumerics folded to hyphens (`save_output` / `slugify` in `last30days.py`).

```text
~/Documents/Last30Days/
├── openclaw-raw-v3.md          # default agent run
├── openclaw-brief.html         # optional HTML export
└── peter-steinberger-raw.md    # person-topic example
```

Step 2.5 in `SKILL.md` requires the hosting model to append WebSearch supplements into the saved raw file under `## WebSearch Supplemental Results` — the on-disk file is the durable citation surface, not only chat output.

## Verify with `--diagnose`

`--diagnose` runs availability probes only — no topic search, no synthesis.

```bash
python3 skills/last30days/scripts/last30days.py --diagnose
```

<ResponseExample>

```json
{
  "available_sources": ["reddit", "hackernews", "polymarket", "github", "grounding"],
  "bird_authenticated": false,
  "bird_installed": true,
  "bird_username": null,
  "has_github": true,
  "has_scrapecreators": false,
  "local_mode": true,
  "native_web_backend": null,
  "providers": {
    "google": false,
    "openai": false,
    "xai": false,
    "openrouter": false
  },
  "reasoning_provider": "auto",
  "x_backend": null
}
```

</ResponseExample>

| Field | Use when verifying |
|---|---|
| `available_sources` | Which platforms the next run can query |
| `providers` / `local_mode` | Whether headless planning needs API keys (`local_mode: true` → deterministic fallback unless the host passes `--plan`) |
| `x_backend`, `bird_*` | X/Twitter auth path (cookies, Bird CLI, xAI, ScrapeCreators) |
| `has_scrapecreators` | TikTok, Instagram, Threads unlock |
| `native_web_backend` | First configured Brave → Exa → Serper → Parallel key |

<Check>
After setup, confirm `youtube` appears in `available_sources` when `yt-dlp` is on PATH, and `x` when cookies or `XAI_API_KEY` / Bird auth is configured. Missing sources with no keys is expected — add credentials per [Configure sources](/configure-sources).
</Check>

`verify_v3.py` in the repo uses the same `--diagnose` call as a release gate.

## Direct CLI smoke test (optional)

For engine testing without the skill contract:

```bash
cd skills/last30days/scripts
python3 last30days.py "test query" --emit=compact --mock
```

Full research requires the skill’s pre-flight flags (`--plan`, handles, subreddits). A bare `python3 last30days.py "Topic"` from cron is supported but uses the engine’s internal planner, not the hosting model’s Step 0.55 / 0.75 resolution.

## Common first-run outcomes

| Outcome | Cause | Next step |
|---|---|---|
| Thin social coverage | No X / TikTok / YouTube keys yet | Run `setup` or add keys; re-check `--diagnose` |
| `## Pre-Research Status` in output | Model skipped Step 0.55 on a named entity | Re-run via slash command with WebSearch; see [Skill contract](/skill-contract) |
| Stale behavior / missing flags | Claude marketplace clone lagging cache | `SKILL.md` STEP 0 stale-clone guard — see [Troubleshooting](/troubleshooting) |
| Permission warning on `.env` | File mode looser than `600` | `chmod 600 ~/.config/last30days/.env` |

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Marketplace, `npx skills add`, Hermes, and live-edit symlinks.
</Card>
<Card title="Overview" href="/overview">
Slash command vs engine paths and zero-config sources.
</Card>
<Card title="Configure sources" href="/configure-sources">
API keys, `.env` layers, and wizard auto-actions in depth.
</Card>
<Card title="CLI reference" href="/cli-reference">
All `last30days.py` flags including `--emit` and `--save-*`.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
`--diagnose` recovery, thin results, and stale installs.
</Card>
</CardGroup>