skills/vectorize-io__hindsight
1
0
Fork 0
mirror of https://github.com/vectorize-io/hindsight.git synced 2026-09-14 19:31:49 +08:00
Code Issues Packages Projects Releases Wiki Activity
2,987 Commits 1,299 Branches 265 Tags
docs-skill-openapi-0.10.0
Commit Graph

8 Commits

Author SHA1 Message Date
Nicolò Boschi 1f513a6393 feat(coding-agents): add ZCode as a supported harness (#4240) (#4258) 
feat(coding-agents): add ZCode as a supported harness (#4240)

Adds ZCode (Z.ai's GLM coding agent) to the shared coding-agents package, so its
users get the same knowledge-page, reflect and configuration experience as every
other supported agent instead of the standalone hindsight-zcode integration.

Three hook registrations, a stdio MCP server and the companion skill, all in
ZCode's own CLI config and home (~/.zcode) — never the user's real Claude Code
settings, even though ZCode embeds the Claude Code agent runtime and speaks its
hook protocol. Config hooks ship disabled, so the installer flips hooks.enabled;
uninstall removes the block again when nothing else is registered there.

The one genuinely new mechanism is a per-session TURN JOURNAL (core/turn-journal.ts).
Every other hook harness hands its Stop hook a file holding the whole conversation,
which is what the incremental write-back needs: retainLiveSession re-reads the full
transcript and the retain cursor sends only the turns added since the last write.
ZCode has no such file — Stop carries the reply plus a temp, assistant-only
transcript it deletes as the hook returns, and no user prompt at all. So the plugin
keeps the conversation itself: the prompt hook appends the user turn, the Stop hook
appends the reply, and retain then reads it exactly as any host transcript. Nothing
downstream changes.

Two host quirks worth knowing, both verified against the runtime rather than assumed:

- hook budgets are `timeoutMs` MILLISECONDS (30000/30000/60000), like qwen-code and
  unlike everything else; the declared timeoutUnit makes that checkable.
- registrations use ZCode's "process" argv shape, not a command string — it spawns
  hooks without a shell, so `node "…/zcode-hook.js"` would be looked up verbatim as
  one executable name and never run.

`--import-conversations` is deliberately unsupported and says why: ZCode persists no
session transcripts, so there is no history on disk to backfill from.

Verified against real ZCode 0.16.5: all three hooks fire with correct bank
derivation, the journal captures the user/assistant pair, `zcode skills list` finds
the companion skill, and all 8 hindsight MCP tools reach the model. A Docker E2E
(e2e/Dockerfile.zcode) asserts injection AND retention end to end against the
published tarball — fuller than grok-build, factory-droid and qwen-code, which are
retention-only. Its entry script merges the stub provider into the config rather
than rendering it, because that file is the same one the installer owns.

Guard tests, since the sibling that forgets is the one nobody tests: a family-wide
check that journalPrompt and retain.journal are declared together, and that a journal
harness parses neither a host transcript path nor a Stop-event reply — both would be
applied on top of the journal, and ZCode's own payload carries last_assistant_message.
 2026-09-09 14:50:26 +02:00
Wojciech Guziak 254bc988d4 feat(coding-agents): add Factory Droid harness (#4011) 
Adds Factory Droid as a supported harness: three hook entry points on Droid's
Claude-shaped protocol, a transcript reader for its JSONL sessions, installer
wiring for ~/.factory (hooks.json, mcp.json, skills/), and the control-plane logo.

Also lands, on top of the original contribution:

- One harness roster for the docs site. The gallery card and the sidebar preview
  kept separate hand-maintained lists and both had drifted — dcode, opencode2, pi
  and prime-agent were each missing from one of them. Both now derive from
  src/lib/coding-agent-harnesses.ts, bound by a test to the registry that decides
  what `install <harness>` accepts, so a new harness cannot ship without its logo
  or its README entry.

- A Docker E2E for the harness. Droid needs no Factory account for it: with a BYOK
  customModels entry it runs fully offline against the stub model.

- A fix to the E2E runner, which drove the container with spawnSync and so starved
  the stub model living in the same process. That silently broke dcode, qwen-code
  and dsh; qwen-code's E2E passes again with it.

Verified end to end against a real Droid session (recall injected, session
retained) and with full CI on ci/4011-factory-droid: 109/109 jobs green.
 2026-09-07 15:56:31 +02:00
Nicolò Boschi 71a9a7008f feat(coding-agents): first-class pi support, sharing one extension adapter and installer with Prime Agent (#3993) 
Adds pi (@earendil-works/pi-coding-agent) as a harness and extracts createPiExtension(harness),
the extension adapter pi and its fork Prime Agent share. Supersedes #3775.

The `pi` key is removed from package.json: both hosts read that same key, so it could only ever
name one bundle, and the host it did not name loaded the other's and reported the wrong harness.
`hindsight-coding-agents install pi|prime-agent` is now the only route for both.

Also makes the companion skill self-update for every host that installs one — the paths now live
once in core/skill-dirs.ts, which both the installer and skill-sync read.

Co-authored-by: Sebastian Otaegui <feniix@gmail.com>
 2026-09-01 15:11:06 +02:00
Nicolò Boschi 1aef228f7b feat(coding-agents): add qwen-code as a hook harness (#3979) 
* feat(coding-agents): add qwen-code as a hook harness

Qwen Code speaks Claude Code's hook protocol field for field -- same stdin
envelope (session_id / transcript_path / cwd / hook_event_name), same
hookSpecificOutput.additionalContext + systemMessage output, same exit
semantics, and a settings.json shape byte-for-byte what cmdHook() already
emits. So HOOK_HARNESSES["qwen-code"] is claude-code's spec with three deltas,
none of which is visible from the diff:

1. TIMEOUTS ARE MILLISECONDS. Qwen passes a command hook's `timeout` straight
   to setTimeout ("Timeout in milliseconds, default 60000" -- its own bundled
   docs/features/hooks.md). Every other harness here is seconds, so the
   installed values are 30000/30000/60000. Writing 30/60 would register 30ms
   hooks, and that misconfiguration LOOKS fine in testing: Qwen spawns without
   detached:true and kills only the direct child, so the orphaned work still
   completes. HookHarnessSpec therefore declares `timeoutUnit`, and the
   lifecycle tests normalise through it -- changing 30_000 to 30, or dropping
   the unit, now fails a test instead of shipping dead hooks. The prompt budget
   must also clear core/hook.ts's HOOK_REFLECT_CAP_MS (25_000).

2. parse reads `submitted_prompt`, not `prompt`. UserPromptSubmit also fires on
   tool-result continuations, where `prompt` holds model-bound tool output;
   keying on it would recall ~20x per user turn against tool results.
   `submitted_prompt` is attached only when the turn is both the first and a
   genuine userQuery. Accepted cost: it is the interactive TUI's projection, so
   headless (`qwen -p`), serve, SDK and ACP sessions seed and retain but never
   recall. The E2E declares injectsIntoModel: false for exactly that reason --
   a different reason from grok-build's passive hook.

3. type:"user" is NOT a user turn. `provenance` is the discriminator: across a
   22-transcript corpus, synthetic records (notification 285, cron 21,
   goal_runtime 1) outnumber real_user ones (69) by 4.4:1. transcript-qwen.ts
   gates on it, rejecting a present-but-malformed value outright rather than
   falling through to a subtype heuristic, and requiring a positive subagent
   marker (agentId/isSidechain) before accepting an absent one -- subagent
   transcripts use a third envelope with neither provenance nor subtype.

Qwen also echoes injected context back into its own transcript, wrapped in
<qwen:user-prompt-submit-context> with the inner tags HTML-escaped, so the
shared stripInjectedMemory (which matches raw tags) cannot see it. The reader
removes it using the two forms of pairing evidence Qwen's contract defines:
systemPayload.hookContext present -> use systemPayload.displayText, the host's
own pre-hook projection, with no tag matching at all; otherwise a COMPLETE
tagged context in the FINAL part after at least one other part. It deliberately
does NOT match the tag as a substring -- the contract is explicit that the tag
is "a provenance marker, not ... a general trust boundary" and that consumers
"must not infer that arbitrary tag-like user text is hook provenance", so a
prompt merely quoting the tag is preserved intact.

Also here:
- registry.test.ts gains the REVERSE parity check. The existing one is
  directional (installer -> registry), so a harness present in the registry but
  missing from INSTALLERS passes it while `install <name>` returns "unknown
  harness". That is exactly how this change was briefly broken.
- readQwenTranscript catches lazy-read faults. readJsonlTail guards
  statSync/openSync, but the generator reads at iteration, and runRetainHook
  calls the reader outside buildRetain's catch -- so a directory passed as
  transcript_path (which passes both guards, then throws EISDIR on the first
  readSync) rejected the whole Stop hook. NOTE: the underlying gap is in the
  shared jsonl.ts and affects every harness; it deserves its own fix rather
  than riding along here.
- Logo asset from homarr-labs/dashboard-icons (Apache-2.0, svg/qwen.svg).

Tests: 675 pass. Note HINDSIGHT_BANK_ID must be unset in the environment, or
config.test.ts's "missing files yield defaults" fails on the leaked value.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WkVVSuv7j1FwTtVpkzzmWR

* chore(coding-agents): regenerate docs artifacts and apply prettier

Address the two CI-blocking review items on #3769:

- Regenerate the two artifacts derived from the README's new Qwen Code
  section: hindsight-docs/docs-integrations/coding-agents.md (via
  sync-coding-agents-doc.mjs) and the docs-skill copy (via
  generate-docs-skill.sh).
- Run prettier over the package with 3.7.4 -- the version CI's root
  `npm ci` pins -- covering the four files the review names, plus
  package.json, where it restores the literal ellipsis in `description`
  that the branch had accidentally left as a unicode escape sequence.

Verified: sync-coding-agents-doc.mjs --check, build-skill.mjs --check,
and prettier --check all pass; 675 tests pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qx1ByUMo3SJhXP7MBxEQ1g

* fix(coding-agents): close the qwen-code harness parity gaps

Rebased onto main (the branch was 98 commits behind and conflicted with the
dcode harness) and closed the sites a new hook harness must also appear in,
found by sweeping every place an existing harness is registered:

- `SKILL_DIRS` (core/skill-sync.ts) did not map qwen-code, so the skill the
  installer copies into ~/.qwen/skills would have been installed once and then
  never refreshed by `npm update -g`. Verified ~/.qwen/skills is Qwen's real
  user-level skills root (Storage.getUserSkillsDirs, SKILL_PROVIDER_CONFIG_DIRS
  = [".qwen", ".agents"]). Added a family-wide guard asserting SKILL_DIRS covers
  every `installSkill` call site, with the five pre-existing gaps (copilot-cli,
  grok-build, cline-cli, dsh, prime-agent) listed explicitly so a new harness
  cannot silently join them.
- The docs site had no qwen-code icon, so the README's own logo would 404, and
  the harness was absent from both coding-agent logo rosters.
- package-lock.json did not carry the three new bins.

Two comments asserted things that are not true of qwen-code 0.22.3 and are
corrected against its source: the hook runner spawns `detached` and calls
`terminateHookProcessTree` on timeout, so a milliseconds/seconds mix-up loses
the retain outright rather than orphaning it; and headless `qwen -p` DOES carry
`submitted_prompt` — the E2E is retention-only because the stub model echoes
only the first 20 000 characters of the request, which Qwen's system prompt
alone exceeds.

Verified end to end against a local API: installed the published tarball into a
container, ran `qwen -p`, and confirmed session_start / reflect_ok / pages_ok /
retain_ok, a document tagged `harness:qwen-code`, and zero injected-memory
leakage in the retained text.

Claude-Session: https://claude.ai/code/session_01DNWFQn8AUN6SApcswHG3aN

---------

Co-authored-by: Mallory M <mallorymiller1984@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-09-01 11:16:02 +02:00
Nicolò Boschi 4388e0f95b feat(coding-agents): add native DeepAgents Dcode integration (#3887) 
Registers `dcode` (LangChain's deepagents-code) as a native Agent Plugin: root `plugin.json`
contributing the shared skill, the Hooks V2 SessionStart/UserPromptSubmit/Stop lifecycle, and the
`hindsight_*` MCP server, installed through Dcode's own marketplace/plugin manager.

Includes fixes found by running it against deepagents-code 0.1.65:

- Decode `last_assistant_message`. Dcode's transcript lags the Stop event, so that field is
  load-bearing, but it is computed as `str(content)` — a Python repr whenever the provider returns
  content blocks. It was retaining ~1.8KB of encrypted reasoning payload as the assistant turn, and
  never comparing equal to the transcript's clean text, so an already-flushed reply was appended
  again every turn. Guarded family-wide: any harness surfacing the field must declare a decoder.
- Annotate the six read-only MCP tools with `readOnlyHint`. Dcode rejects unannotated MCP calls in
  headless mode, which made recall and the knowledge-page tools unusable under `dcode -n`.
- Parity: local history import (attributed via `dcode threads list --json`, since the transcripts
  carry no cwd), a Docker E2E adapter and image, the harness icon on the docs site as well as the
  control plane, and a clean uninstall that also retires the marketplace it registered.
- Document that Dcode cannot host the codebase survey: `hindsight_ingest_document` writes, so its
  headless runtime gates it by design; it falls back to another agent's CLI like eight other
  harnesses.

Supersedes #3887.

Co-authored-by: Paritoshdagar <paritoshdagar@gmail.com>

Claude-Session: https://claude.ai/code/session_01DNWFQn8AUN6SApcswHG3aN
 2026-09-01 10:13:24 +02:00
Nicolò Boschi 28760f62d4 feat(coding-agents): DeepSeek Harness (dsh) support (#3504) 
Adds `dsh` as a persistent-plugin harness: a native Cordis plugin that binds
DeepSeek Harness's typed lifecycle events to the shared RuntimeCore.

  agent/session-start  -> seedIfCold      (cold check + background seed)
  agent/pre-step       -> onPrompt        (recall) + the injection as a
                          `{kind:'plugin', form:'recall'}` message
  agent/turn-stopping  -> onSessionIdle   (write-back of the completed exchange)
  ctx.tools            -> the hindsight_* suite, registered natively

Its Claude Code / Codex hook bridges are deliberately not used: neither ships in
a default profile, so a bridge would cost the same install while losing the
session id, the transcript and the awaited stop boundary.

dsh is the first host where ONE process serves SEVERAL repositories — its Web UI
opens each session in whatever directory the user picks — so the bank, client and
seed are resolved per session workspace and the core is constructed with that
workspace root, which is what binds the tools' git checks to the right repo.

The plugin imports nothing from dsh: host shapes are structurally typed and tool
definitions are built in the registry's own shape, so there is no dsh package for
pnpm to resolve inside a profile and no version to keep in step.

Also here:
- backfill reads dsh session logs. They are a CONCATENATION of zstd frames, and
  both of Node's decoders stop after the first one — a plain decompress returns
  only the header line — so core/zstd-frames.ts walks the frame structure and
  decodes each frame (RFC 8878 §3.1).
- transcript normalization keeps only `source.kind === 'user'` messages: dsh
  delivers plugin context (its runtime snapshots, the skill catalog, our own
  recalled memory) as user-role messages on the same surface.
- describeError: Node's fetch reports every transport failure as the bare string
  "fetch failed" and hides the reason on `cause`, which made an unreachable
  apiUrl an investigation instead of a log line.
- vitest pins HINDSIGHT_CONFIG at a path with no file; loadConfig otherwise
  resolved the developer's real ~/.hindsight/coding-agent.json, so a machine with
  a token configured failed assertions a clean machine passed.

Verified against @deepseek-ai/dsh 0.1.0-rc.6: recall reaches the model, all 8
tools reach the model and dispatch, sessions are retained, and the Docker E2E
(e2e/Dockerfile.dsh, driven through the stub model like the other credential-less
harnesses) runs the whole lifecycle in a container.
 2026-08-14 17:56:57 +02:00
Ben 29cd6c6ab0 feat(coding-agents): add Prime Agent as a supported harness (#3240) 
* feat(coding-agents): add Prime Agent as a supported harness

Adds Prime Agent (PrimeIntellect) as a plugin harness in
@vectorize-io/hindsight-coding-agents, giving it the shared reflect-and-inject
core (auto-seed, knowledge pages, attribution, per-repo bank naming) like
opencode/cline. A Prime Agent extension entry (src/prime-agent.ts) wires
before_agent_start -> recall + system-prompt injection and agent_end ->
transcript write-back onto RuntimeCore, and registers the hindsight_* knowledge
tools natively via pi.registerTool (Zod raw shape -> JSON Schema; Prime Agent
forwards it to the model provider). Installer registers the built extension in
~/.prime/agent/settings.json; registry lists it for backfill. Includes a
transcript normalizer, unit tests for the hooks/tool adapter/converter/installer,
a README entry, and the synced docs page.

Supersedes the standalone @vectorize-io/hindsight-prime-agent package.

* fix(coding-agents): register Prime Agent in the control plane, wire its E2E, pass the workspace

Follow-ups from review, on top of a rebase onto main (the branch was 66 commits
behind and predates the append write-back, bounded transcript reads, the retain
stamp and both 0.2.x releases).

Control-plane registry. CLAUDE.md requires a new harness to land its logo entry
in the same change, and this one didn't: documents retained by Prime Agent carry
metadata.harness = "prime-agent" and a harness:prime-agent tag, which the
documents list resolves a logo from, so every one of them rendered as bare
metadata. Verified against a real local run before fixing. Neither guardrail
catches this — the parity test's EMITTED_HARNESSES is a hand-maintained list, and
it lives in the control plane, so `detect-changes` never runs it for a
coding-agents-only PR. Added to the registry, the icon copied into
public/img/harness, and the id added to that list so it is covered from now on.
The mark is dark line art, so invertOnDark like the other monochrome ones.

E2E. Every other harness has a Docker E2E entry; this one had none. Added
Dockerfile.prime-agent and a setup entry, so it joins the roster that installs
the CLI, seeds a bank with a decision the prompt never mentions, and requires the
agent to carry it back out. It skips cleanly without credentials, like the rest.
Prime Agent ships no npm package — the upstream repo is a private monorepo — so
the image uses the vendor installer and puts ~/.local/bin on PATH.

createRuntime passed four arguments to RuntimeCore, dropping the workspace
directory added in #3346. Harmless today because repoPath is process.cwd(), but
{gitProject} and {project} in retainTags/retainMetadata would silently resolve
against the wrong directory the moment those diverge; plugin-entry and cline both
pass it explicitly.

Regenerated the docs skill mirror, which verify-generated-files was failing on.

---------

Co-authored-by: Nicolò Boschi <boschi1997@gmail.com>
 2026-08-12 07:03:48 +02:00
Nicolò Boschi fecacc4ea8 docs: launch Coding Agents + mark the per-agent plugins superseded (#3162) 
* docs: launch the Coding Agents page and mark the per-agent plugins superseded

Hold until the Coding Agents plugin is announced — merging this makes the page
public and tells existing users their plugin is legacy, so it should land with
the announcement rather than before it.

Two halves:

- Launch. Undoes the deliberate hide: the page drops `unlisted`, its entry
  returns to integrations.json (which drives both the gallery and the sidebar),
  and coding-agents leaves the EXCLUDED set in check-integrations.mjs, so the
  released-tag check guards it like every other integration.

- Supersede. The six overlapping integrations — claude-code, codex, opencode,
  cursor-cli, cline, copilot-cli — get an admonition in the style already used
  on the Hermes page: what replaces them, the install command for their harness,
  and a link to the migration section. Pages and packages keep working; nothing
  is deleted and no registry deprecation is published, so existing links and
  installs are unaffected.

Each notice states plainly that memory does not move — the old plugins scope a
bank per agent per project where this one uses a bank per repo — and points at
`--import-conversations` for Claude Code and Codex, the two whose transcripts
record enough to attribute a session to a repo. The other four say so instead of
implying an import exists.

* docs: group the integrations sidebars into coding agents / frameworks / apps

Both sidebars driven by integrations.json rendered one flat run of 59 entries.
Split them into three groups so a coding agent is distinguishable from an SDK.

The existing `category` field couldn't drive this on its own: its `tool` bucket
mixed CLI agents and editors with chat apps, note-taking and voice platforms.
The 19 coding agents move to a new `coding-agent` category; `framework` is
unchanged, and `tool`/`mcp` become the catch-all group.

Grouping lives in src/lib/integration-groups.ts, kept free of the @site alias and
of any JSON import so both consumers can use it — the theme swizzle (webpack) and
sidebars-integrations.ts (evaluated at config load). An unrecognised category
falls into the last group rather than disappearing from the sidebar.

* docs: regenerate the docs-skill mirror for the supersede admonitions

scripts/generate-docs-skill.sh mirrors docs-integrations/ into skills/; the
launch commit edited seven pages without re-running it, so the mirror still
described the per-agent plugins as current.

* docs: spell out the migration path for Claude Code and Codex

Both pages said memory "does not move automatically", which is now only half
true: the server endpoint IS carried over (~/.hindsight/claude-code.json and
~/.hindsight/codex.json, same keys), so nobody is silently switched to Cloud.

Each page now states what moves — the endpoint automatically, conversations via
--import-conversations — and what does not: the recall/retain settings, missions
and bank-naming options. It also says why conversations come from local
transcripts rather than the old bank: that bank defaulted to a single static
bank shared by every project, whose documents record only a session id, so
attributing them to a repo requires the local transcripts regardless.

These are the only two superseded plugins with an endpoint to carry; the other
four pages already say their history can't be imported and are unchanged.

* feat(claude-code,codex): deprecation notice in the old plugins' sessions

Folded in from #3205 so the launch lands as one change: the docs that announce
the Coding Agents plugin and the in-session notice that points existing users at
them ship together, rather than one arriving without the other.

Both plugins keep working, but they are deprecated — development has moved to
@vectorize-io/hindsight-coding-agents. A changelog entry reaches nobody who
installed a year ago, so the SessionStart hook says it, via systemMessage (the
channel Claude Code shows the USER; additionalContext would only reach the
model). Codex accepts the same hook output shape, so one design serves both.

Emitted before the existing early returns: neither the memory settings nor
whether the server is reachable changes the fact that the plugin is deprecated.

Shown every session, with `"upgradeNotice": false` as the permanent opt-out —
stated in the message itself, which is what makes that frequency acceptable.
With no rate limit there is no state file and none of its failure modes; what
remains is a config check that returns None rather than raising, because a
promotional message must never be why a session breaks.

* docs: per-harness install sections, featured hub cards, browsable sidebar

Page
- One subsection per harness with its logo and a copyable install command,
  replacing the table: the command is what a reader came for, and a table cell
  is not copyable.
- Title is just "Coding Agents"; the old keyword-stuffed title read as spam in
  the sidebar and breadcrumbs.
- "Ingestion internals (no CLI)" is dropped from the docs page via the existing
  DROP_SECTIONS mechanism, staying in the README where the contributor-facing
  audience is.

Integrations Hub
- A Featured grid pins Coding Agents, Vercel AI SDK and OpenClaw above the
  rest, and only on the unfiltered view — pinned cards above non-matching
  search results would read as noise.
- The Coding Agents card draws all ten supported harness logos. "One install,
  every agent" is the whole pitch and a single icon cannot carry it.
- Logos come from the control plane's harness set, which is already keyed by the
  exact harness ids the plugin uses, so the two stay consistent by construction.

Sidebar
- Groups are open but show six entries each, with the tail behind a nested
  "Show all N". Fully expanded, 59 entries were a wall; fully collapsed hid that
  the list was worth opening.
- The umbrella Coding Agents entry leads its group instead of sorting under "C",
  since it is the entry point to every other agent in that list.

* fix(docs): point the page's harness logos at this build, not production

The README must use absolute URLs so the logos render on npm and GitHub, but the
docs page inherited them verbatim — pinning every image to hindsight.vectorize.io,
where /img/harness/* does not exist yet. Logos were broken locally and in
previews, and would only start working after a deploy.

The sync script now rewrites our own absolute asset URLs to site-relative, next
to the repo-relative-link rewrite it already does for the same reason: two
audiences needing different URLs from one source.

* docs: curate the sidebar previews, harness logos for coding agents

The coding-agent group now previews HARNESSES, not pages: ten logos that all
link to the Coding Agents page. Listing ten integration pages there presented
one plugin as ten separate integrations, which is the opposite of its pitch —
and the logos make the group recognisable at a glance. Every individual page
moves behind "Show all", which is also what keeps it associated with the
sidebar.

The other groups get hand-picked previews instead of the first six
alphabetically — the first names in a sorted list are an accident of spelling,
not a description of the group:
  Frameworks & SDKs — LangGraph/LangChain, Vercel AI SDK, Vercel Chat, Eve, CrewAI
  Apps & tools      — ChatGPT, Hermes, OpenClaw, Obsidian

Hermes, NemoClaw, OpenClaw and Paperclip move from framework to tool.

The overflow label counts what opening it actually reveals: "Show 21 more" where
some entries are already previewed above, "Show all 19" for coding agents, whose
overflow really is every page.

* docs: inline sidebar preview, full list on the integration pages

The two sidebars do different jobs, so they now show different things.

Main docs sidebar — a preview: three groups rendered INLINE and
non-collapsible, nothing behind a disclosure. Ten harness logos for coding
agents, five frameworks, four apps, then an "All integrations" link to the
gallery, which offers search and filters a sidebar cannot.

Integration pages — the full list again: flat, alphabetical, every entry. Once
you are on one of these pages you are comparing and hopping between them, so
hiding two thirds behind "Show N more" worked against the reader. Listing each
page directly is also what associates it with this sidebar.

* docs: promote the sidebar groups, separate Featured, brand the umbrella card

Sidebar: the "Integrations" placeholder is replaced BY its contents instead of
filled, so the three groups sit at the same level as the rest of the navigation.
The wrapper was two levels of nesting to say one thing, and it indented every
entry beneath it.

Hub: a divider and an "All integrations" heading separate the pinned Featured
cards from the full list, which otherwise read as one uninterrupted run.

The Coding Agents card carries the Hindsight mark rather than the GitHub logo —
it is our own package, and the GitHub icon said nothing about it.

* docs: install with npx, no global install

Every example across the README, the seven integration pages, the companion
skill and the generated docs now runs the installer with npx. Nothing here asks
anyone to keep a package installed whose only job is to wire other tools up.

The paragraph telling people to install globally — and warning that npx was
refused — is replaced by what actually happens: install copies what it needs
into ~/.hindsight/coding-agents and points each agent's wiring there, so it does
not matter where it ran from, and updating is the same command again.

Depends on #3241, which makes that staging real; until it ships in 0.0.6 the
published installer still refuses to run from an npx cache.

* docs: move the superseded pages into a Legacy section, out of the gallery

The six per-agent pages the Coding Agents plugin replaces — Claude Code, Codex,
Cursor CLI, Copilot CLI, opencode, Cline — move to a `legacy` category.

They keep their pages and their migration banners: people still run these
plugins and still arrive from old links, so removing the pages would break both.
What changes is where they are offered. The gallery is where someone comes to
CHOOSE an integration, and offering one we are actively migrating them off
points them at a dead end — so legacy entries are filtered out of it, including
the hero banner, whose hardcoded list still advertised Claude Code and now
advertises the plugin that replaced it.

In the sidebar they sit in a collapsed "Legacy" section at the end instead of
mixed in alphabetically, so the main list is only what we would recommend today.
Docusaurus expands that section automatically when you are on one of the pages.

Grouping keys off an explicit `harnessPreview` flag now: "no previewIds" used to
imply the coding-agent group, which the Legacy group would also have matched.
 2026-08-07 17:00:50 +02:00