research: X social discovery harvest run (candidate claims only, public URLs, date precision)

.claude/skills/frontier-cycle/SKILL.md

@@ -108,6 +108,25 @@ profiles, and recent digests. Identify the nearest precedent, concurrent pattern
 or structural divergence. Do not force a comparison when it does not change the
 read.
 
+#### X/Grok social-discovery lane (standard step)
+
+Each cycle, after the primary-source harvest, drive the X social-discovery lane:
+the loop runs the Hermes agent as a one-shot sub-agent (`hermes -z`) with its
+web/X search tools on Grok, through a SuperGrok or X Premium+ subscription, to
+surface maintainer intent, adoption, and ecosystem tension a changelog does not.
+Run `ops/hermes/grok-harvest.sh harvest <source> <start> <end>` per watched source;
+it writes candidate claims into an `x-social-harvest` run. Setup is in
+`docs/hermes-grok-harvest-setup.md`.
+
+This lane runs every cycle, but it is **discovery only**: its output is leads,
+never receipts. No X or Grok claim becomes a finding, signal, digest, or profile
+until it clears the source contract's evidence floor against a primary source, per
+`docs/x-social-harvest-workflow.md`. It feeds the harvest alongside, never instead
+of, primary sources. Grok's subscription surface can reject a valid subscriber with
+HTTP 403; `grok-harvest.sh` degrades the lane (records the gap, exits soft) so a
+refusal never fails the cycle. When the lane is down, note it in `qa.md` and
+proceed on primary sources.
+
 ### 4. Findings
 For every source-backed observation write `findings/<finding_id>.md` -- an index
 stub: frontmatter (`finding_id`, `source`, `source_contract`, `window`, `status`,

AGENTS.md

@@ -46,6 +46,11 @@ House style: ASCII punctuation only, no em dashes; operator-first, skeptical,
 plain, and free of hype or sneer. The publication absorbs complexity for the
 reader. A first-time visitor should not have to learn the repository taxonomy.
 
+For reader-facing prose, the repo-local [humanizer skill](./skills/humanizer/SKILL.md)
+is the tool for the last pass: public copy should sound like a sharp person
+explaining the idea clearly, with traceability and research-process details
+pushed into quieter source layers.
+
 ## Validate before you push
 
     npm --prefix site run build

CONTRIBUTING.md

@@ -64,6 +64,17 @@ A coverage gap must carry a receipt and an event date inside the claimed
 publication window, plus which artifact should have caught it (which window's
 digest, which profile).
 
+For public X/social discovery that may become a coverage gap later, use the
+[X Social Harvest Workflow](./docs/x-social-harvest-workflow.md). Social harvests
+are candidate inputs only; product/version claims still need source-contract
+cross-checks before promotion.
+
+For deeper public-conversation work, including static tweet-like receipt cards
+and ecosystem-drama cataloging, use the
+[Deep Social Research Loop](./docs/deep-social-research-loop.md). The loop keeps
+cards repo-local and treats social posts as context until source contracts
+support promotion.
+
 ### 3. New-source proposals
 
 A proposal to add a watchlist source contract (a new provider) or an

README.md

@@ -155,6 +155,35 @@ Use the other objects according to the job:
 The chain is `source -> finding -> signal -> digest -> profile`. Most findings
 never become signals. The gap is the editing, and it protects reader attention.
 
+## Running the research toolchain
+
+The weekly cycle is produced by the `frontier-cycle` skill, source-backed from
+primary changelogs, commits, and releases. One standard harvest step also digs
+public X for leads: the loop drives the
+[Hermes agent](https://hermes-agent.nousresearch.com/) as a one-shot sub-agent on
+Grok, through a SuperGrok or X Premium+ subscription. Those leads are discovery
+only. They never enter the record without a primary-source cross-check.
+
+To stand that lane up on a fresh clone (Hermes installs globally, not into this
+repo; the OAuth step needs a browser and your subscription login):
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash   # global install
+exec "$SHELL" -l                                                      # reload PATH
+hermes auth add xai-oauth --type oauth                               # or: hermes model
+hermes model                                                         # pick a Grok model
+ops/hermes/grok-harvest.sh doctor                                    # confirm the lane
+```
+
+Then dig one source over the reporting window:
+
+```bash
+ops/hermes/grok-harvest.sh harvest codex 2026-07-02 2026-07-21
+```
+
+Full setup, the subscription path's two limits, and the secret boundary are in
+[docs/hermes-grok-harvest-setup.md](./docs/hermes-grok-harvest-setup.md).
+
 ## Contributing
 
 Corrections, coverage gaps, new-source proposals, and mechanical fixes are

docs/deep-social-research-loop.md

@@ -0,0 +1,114 @@
+# Deep Social Research Loop
+
+This workflow turns public X/social material into a richer research layer for
+Bitter Frontier without relaxing the evidence floor for product claims.
+
+The loop has three roles:
+
+- Scout: mines public social posts for interesting facts, public exchanges,
+  adoption signals, user pain, maintainer intent, benchmark discourse, and
+  ecosystem drama.
+- Critic: challenges the scout packet for overclaiming, missing counter-posts,
+  weak source attribution, and unclear operator relevance.
+- Editor: stores only reproducible artifacts in the repo, writes cautious
+  summaries, and decides what remains social context versus what deserves a
+  later source-contract verification pass.
+
+The role names are generic. Do not record private session identifiers, model
+transcripts, raw API payloads, local paths, private prompts, reviewer names, or
+credentials in public artifacts.
+
+## Output Shape
+
+A social research run may include:
+
+```text
+runs/<run-id>/
+  manifest.yml
+  editorial.yml
+  harvest/*.md
+  social-cards/*.yml
+  research-journal.md
+  verify/*.md
+  qa.md
+```
+
+`harvest/*.md` keeps structured candidate claims. `social-cards/*.yml` stores
+static post artifacts the site can embed inside editorial. `editorial.yml` is
+the public reading experience: argument first, evidence woven into the essay,
+with traceability pushed into source links or a collapsed source trail.
+`research-journal.md` records editorial decisions, open loops, and what the next
+scout pass should investigate.
+
+## Publication Rule
+
+The public page should read like a finished editorial, not a research binder.
+Use X/social material to sharpen the story, show the public conversation, and
+surface questions a release-note-only workflow would miss. Do not lead with raw
+receipts, card grids, QA notes, claim tables, or artifact inventories.
+
+Traceability remains mandatory, but it belongs in the background: source links
+on the embedded post figure, collapsed evidence notes, repo artifacts, and the
+Git history. A reader should be able to audit the piece without having the audit
+machinery interrupt the piece.
+
+## Static Social Cards
+
+Social cards simulate the useful parts of an embedded post while keeping runtime
+independent from X. They are source material for editorial embeds, not the
+primary public artifact:
+
+```yaml
+schema_version: bitter.frontier_social_cards.v0
+run_id: 2026-06-24-x-social-harvest-2026-06-24-frontier-v0
+cards:
+  - id:
+    title:
+    kind: capability_announcement | maintainer_intent | user_pain | adoption_signal | benchmark_discourse | ecosystem_drama | public_exchange | governance_or_affiliation | meme_or_positioning
+    status: candidate | social_context | single_source_unconfirmed | needs_primary_crosscheck | verified_secondary | refuted | superseded
+    date: YYYY-MM-DD
+    date_precision: day | month_only | year_only | unknown
+    date_note:
+    source_ids: []
+    authors: []
+    source_urls: []
+    excerpt:
+    summary:
+    why_it_matters:
+    verification_needed:
+    confidence:
+    caveats:
+    tags: []
+```
+
+Use short excerpts only. Prefer a neutral summary plus a source link over long
+quoted text.
+
+## Evidence Boundaries
+
+- A social card can make the journal more grounded and readable.
+- A social card is not, by itself, a finding, signal, digest claim, or profile
+  claim.
+- Product/version/capability claims still need source-contract verification
+  before promotion.
+- A secondary receipt upgrades only the exact bounded claim it proves. Do not
+  let a real release tag or PR validate a different claim from the same project.
+- Drama, public exchanges, rankings, benchmark chatter, and user pain may be
+  cataloged as ecosystem context when clearly labeled.
+- If a claim depends on a thread or reply chain, keep enough public source URLs
+  to let a reader reconstruct the exchange.
+- Reputational or conduct claims about named people or organizations stay
+  journal-only unless supported by direct primary receipts.
+- User-pain and drama clusters should include counterweight searches: fixes,
+  maintainer replies, disconfirming posts, issue threads, or release notes.
+
+## Loop Cadence
+
+1. Scout one slice: a project, theme, or date window.
+2. Critic pass: reject weak items, ask for missing context, and identify
+   follow-up searches.
+3. Editor pass: write or revise social cards, journal notes, and caveats.
+4. Repeat until the remaining open questions are specific verification tasks,
+   not broad social discovery gaps.
+5. Run `git diff --check`, `node site/scripts/check-integrity.mjs`, and the site
+   build before publishing.

docs/hermes-grok-harvest-setup.md

@@ -0,0 +1,122 @@
+# Hermes + Grok X social-discovery setup
+
+This runbook wires one recurring step of the Bitter Frontier cycle: the loop drives
+the [Hermes agent](https://hermes-agent.nousresearch.com/docs/) as a one-shot
+sub-agent that digs public X/social signals on Grok, using a SuperGrok or X
+Premium+ subscription. Its output is discovery leads for the watchlist.
+
+It is operational plumbing, not reader-facing prose. It lives in `docs/` and
+`ops/`, never in `content/`. The short bootstrap is mirrored in the README so a
+fresh clone can stand the lane up in four commands.
+
+## The one rule that governs this lane
+
+**Discovery only. Leads, never receipts.** Nothing Grok or X produces here may
+become a finding, signal, digest, or profile until it clears the relevant source
+contract's evidence floor against a primary source. The evidence rules, run shape,
+and cross-check discipline live in `docs/x-social-harvest-workflow.md` and
+`docs/deep-social-research-loop.md`. This document only covers standing up the tool
+that feeds them.
+
+A social post tells you where to look. It cannot tell an operator to upgrade,
+migrate, or trust a feature. That is why this lane is quarantined from the
+receipted record even though it runs every cycle.
+
+## How the loop drives it
+
+The orchestrating agent (the one running the cycle) drives Hermes as a subordinate
+one-shot agent. `hermes -z "<prompt>"` is Hermes' purest headless entry point:
+one prompt in, the agent's final text out, nothing else on stdout. The agent runs
+its full toolset (web and X search) on Grok and returns the leads.
+`ops/hermes/grok-harvest.sh harvest <source>` wraps that call for one watched
+source and writes the result into an `x-social-harvest` run.
+
+You do not need the HTTP gateway for this. `hermes gateway run` (an
+OpenAI-compatible server on `127.0.0.1:8642`) is only useful if you want a
+*different* application to borrow the subscription; driving Hermes from the loop
+is a plain `hermes -z` call.
+
+## The access path, and what to watch
+
+We drive Grok through Hermes' `xai-oauth` provider, which authenticates against a
+SuperGrok or X Premium+ **subscription**, not a metered xAI API key.
+
+**The model catalog is live, so do not hardcode a version.** Hermes derives the
+chat catalog from an on-disk `models.dev` cache, and new xAI releases appear once
+that cache refreshes. The
+[xAI Grok OAuth guide](https://hermes-agent.nousresearch.com/docs/guides/xai-grok-oauth)
+lists older entries (`grok-build-0.1`, `grok-4.3`, the `grok-4.20-0309-*`
+variants), but that list goes stale: verified on 2026-07-22 with Hermes v0.19.0,
+`grok-4.5` was offered by `hermes model` and served normally over the subscription.
+Run `hermes model` and take the best model the catalog actually shows you.
+
+**A valid subscriber can still be refused.** xAI enforces its own allowlist on the
+OAuth API surface and has been reported to reject active SuperGrok subscribers with
+`HTTP 403`. Not encountered on this account as of 2026-07-22, but treat it as a
+live failure mode: `grok-harvest.sh` classifies a 403 as a degraded lane rather
+than a cycle failure, records the gap, and lets the primary-source harvest proceed.
+
+The metered xAI API key remains the alternative if the subscription surface ever
+becomes unreliable for unattended runs. This runbook deliberately runs on the
+existing X subscription per the current operating choice.
+
+## Bootstrap (fresh machine)
+
+Hermes installs globally, not into this repo. The installer clones to
+`~/.hermes/`, puts the binary at `~/.local/bin/hermes`, uses `sudo` for optional
+system packages, and appends `~/.local/bin` to your shell rc. Prerequisite on
+non-Windows is Git (the installer brings Python 3.11, Node 22, ripgrep, ffmpeg).
+
+```bash
+# 1. Install Hermes (system-wide; needs an interactive shell, may prompt for sudo)
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+exec "$SHELL" -l                              # reload so `hermes` is on PATH
+
+# 2. Authenticate Grok over the subscription OAuth device-code flow (needs a
+#    browser and your SuperGrok / X Premium+ login)
+hermes auth add xai-oauth --type oauth        # or: hermes model  (pick "xAI Grok OAuth")
+
+# 3. Select the model from the OAuth catalog
+hermes model                                  # choose a grok-4.20-0309-* reasoning variant
+
+# 4. Confirm the lane end to end
+ops/hermes/grok-harvest.sh doctor
+```
+
+`doctor` runs `hermes doctor` (Hermes' own environment check) and then a one-shot
+Grok probe. A `403`/allowlist refusal reports the lane as degraded (see limit 2).
+The OAuth refresh token is stored under `~/.hermes/`; it never enters this repo.
+`ops/hermes/config.template.yaml` shows the shape of `~/.hermes/config.yaml`.
+
+## Per-cycle run
+
+```bash
+# Dig one source over the reporting window. Repeat per source, or let the
+# frontier-cycle harvest step call it.
+ops/hermes/grok-harvest.sh harvest codex 2026-07-02 2026-07-21
+```
+
+This drives `hermes -z` with a discovery prompt and writes candidate claims to
+`runs/<date>-x-social-harvest-<window>-frontier-v0/harvest/<source>.raw.md`. Then
+hand the raw harvest to the cross-check pass in `docs/x-social-harvest-workflow.md`:
+keep only exact public post URLs with resolved dates, mark every product or version
+claim `needs_primary_crosscheck`, and promote nothing until a primary source clears
+it.
+
+## The secret boundary
+
+- No credentials in this repo, ever. The OAuth refresh token lives in `~/.hermes/`
+  and is managed by Hermes. This script and template never read, write, log, or
+  print it.
+- If you ever run `hermes gateway run`, keep it on loopback: the endpoint accepts
+  any bearer token and has no auth of its own, so a non-local bind exposes your
+  subscription to the network.
+- Do not paste raw API payloads, private prompts, session IDs, or local paths into
+  public run artifacts, per the workflow doc.
+
+## Primary sources for this setup
+
+- Install: https://hermes-agent.nousresearch.com/docs/getting-started/installation/
+- CLI commands (`hermes -z`, `auth add`, `model`, `doctor`, `gateway`): https://hermes-agent.nousresearch.com/docs/reference/cli-commands
+- xAI Grok OAuth: https://hermes-agent.nousresearch.com/docs/guides/xai-grok-oauth
+- xAI pricing and the API-versus-subscription distinction: https://docs.x.ai/grok/faq