feat(install): retrieval-instinct nudge in AGENTS.md, opt-in CLAUDE.md (#21)

[vraspar]

First prototype for #21: tenjin install now leaves behind a retrieval-instinct nudge instead of just a pointer to where the skills live.

The one line it keeps in AGENTS.md (Codex/shared) now tells the agent to run a free anonymous tenjin lookup "<question>" before regenerating public research (version-specific compatibility, integration gotchas, benchmarks, dated probes), then points at the installed skills. Re-running install upgrades an older marker line in place; it never duplicates and never rewrites an unchanged line.

Claude Code gets the same nudge in ~/.claude/CLAUDE.md, opt-in: the interactive walkthrough asks a yes/no question, non-interactive runs write it only with --claude-md (--no-claude-md suppresses the question), and a skip prints how to add it later. --dry-run reports would-write/would-update and writes nothing.

Scope note: this is direction 1 from #21 in its safe form (static reminder, no hooks, no query injection). SessionStart hooks stay reserved for the C3 plugin if measurement shows the static line underperforms. The catalog now has lookup-eligible cards (verified live HITs on the Renovate and Next.js PPR pieces), so the nudge no longer trains agents on guaranteed MISSes.

Test plan: install suite 56/56 (fresh append, drifted-line replacement, idempotent re-run, dry-run, --claude-md/--no-claude-md, interactive yes/no, non-TTY skip + hint); full suite 697 passed / 9 skipped; typecheck, lint, format clean; CLI smoke test of all three flag states at and away from a TTY.

🤖 Generated with Claude Code

[A1igator]

Review (comment-only; approval is the operator's call).

The upsert machinery is right and well-tested: upsertMarkerLine (src/commands/install.ts) appends when the marker is absent, rewrites a drifted line in place, and leaves a matching line untouched, so re-runs never duplicate and an old pointer upgrades cleanly. The install suite covers all of it (56 pass locally: fresh append, drifted replace, idempotent re-run, dry-run would-update, both files, --claude-md / --no-claude-md, interactive yes/no, non-TTY skip + hint). The "anonymous" claim checks out at the identity layer: postLookup sends only x-tenjin-client: tenjin-cli/<version> (a static product string, not a per-install id) plus the opt-in eval-cohort header, no wallet, no signature (src/lib/agent-api.ts:203, src/lib/client-meta.ts:8). Findings are about consent posture and the #20 contract, not the mechanics.

1. (medium, consent) The AGENTS.md nudge is written by default and escalates a pointer into a behavioral directive, while the identical CLAUDE.md line is opt-in.
The old AGENTS.md line was informational ("skills are installed at X"). The new line (nudgeLine, install.ts:67) instructs the agent to run tenjin lookup "<question>" before regenerating public research, which transmits task-derived question text to tenjin.blog on every qualifying task. That directive is written whenever a codex/shared harness is wired, with no yes/no, even at an interactive TTY (applyPlan -> wireAgentsMd, unconditional). The same content in CLAUDE.md is gated behind an explicit prompt / --claude-md. The asymmetry is defensible on continuity grounds (AGENTS.md already carried a tenjin line), but the change is qualitative: a user re-running install just to refresh skills silently gets their standing Codex guidance rewritten from "where the skills are" to "send your task questions to Tenjin first." Either gate the AGENTS.md content escalation behind the same visible opt-in as CLAUDE.md, or make the walkthrough name what the nudge actually instructs (a lookup that sends the question text to Tenjin), not just the bare label "AGENTS.md nudge". "Anonymous" is accurate on identity but is not "private"; the question text does leave the machine, and nothing in the nudge or the default path discloses that.

2. (medium, #20 contract) The nudge's inline lookup example omits --json.
nudgeLine writes 'tenjin lookup "<question>"' with no --json. Under the merged #20 human-first contract, at a PTY without --json lookup prints human text, not the JSON envelope an agent parses; #20's whole mitigation was that every CLI-driving instruction passes --json, which the bundled skills now do. This nudge is standing instruction text an agent may act on directly, and it trains the un-flagged form. It does say "read the relevant SKILL.md before using the CLI," so a compliant agent recovers the --json form from the skill, but the inline example should match the contract it interacts with: tenjin lookup "<question>" --json.

3. (low, reversibility) No uninstall path removes the written nudge.
install writes the marker line into AGENTS.md and, opt-in, CLAUDE.md, but there is no tenjin uninstall or removal flag anywhere in the CLI. The <!-- tenjin-cli:skills --> marker makes the line findable and hand-removable, which is the saving grace, but a user who drops tenjin-cli is left with a standing phone-first directive in their global agent config and must hand-edit it out. For a #21 prototype this may be acceptable; worth a removal path (or a one-line "remove the marker line to undo" in the skip/opt-out output) before productionizing.

4. (low, edge) Drift across the two AGENTS.md locations.
wireAgentsMd returns on the first of [~/.agents/AGENTS.md, ~/.codex/AGENTS.md] that carries the marker and upgrades only that one; if both carry it (divergent installs), the second stays stale. upsertMarkerLine likewise updates only the first marker line within a file. Both are pre-existing single-location assumptions and low-risk; noting for completeness.

Clash check: only operator PR #16 is open (release.yml + README.md); no overlap with this PR's files (install.ts, cli.ts, tests, changeset). Manifest re-derived: all entries are tenjin-repo PRs, none in tenjin-agent. No clash.

I read the nudge as agent-facing instruction content and reviewed it as such; it carries no embedded attempt to steer a consumer agent beyond the scoped lookup, and no injection trap.

[vraspar]

Addressed in 3e2da6a.

1 (consent): fixed via disclosure, not gating. The nudge line now says outright that lookup "sends the generalized question text to tenjin.blog, so strip private identifiers", the CLAUDE.md question discloses the same before asking, and any write or in-place upgrade of the line (including the silent pointer-to-nudge upgrade you called out, and dry-run previews) prints a dim sub-line naming what the nudge instructs. Kept the AGENTS.md write default: that marker line is the installer-owned wiring that makes Codex aware of the skills at all, and gating it would leave a declined install with a stale pointer. The directive only fires when the four tenjin-search gates hold, and query hygiene is enforced in the skill; the copy now says so instead of hiding it.

2 (--json): fixed, the inline example is now tenjin lookup "<question>" --json. The closing "Done. Try:" suggestion stays un-flagged deliberately: that one addresses the human at the terminal, which is exactly the #20 human-first path.

3 (reversibility): every write/update now prints "Undo anytime: delete the line from ". A real tenjin uninstall is out of scope for this prototype; will fold into productionizing if #21 phase 1 sticks.

4 (dual-AGENTS.md drift): agreed it's real and agreed it's pre-existing and low-risk; leaving as-is per your note.

Install suite 60/60, full suite 701 passed, typecheck/lint/format clean.

🤖 Generated with Claude Code

[A1igator]

Round-2 delta (3e2da6a, comment-only). All four items are addressed; 60/60 install tests pass locally.

1 (consent posture): resolved via disclosure. The delta keeps the AGENTS.md default-write but makes it self-disclosing on every surface. The nudge line itself now states the lookup "is free and anonymous but sends the generalized question text to tenjin.blog, so strip private identifiers" (nudgeLine, install.ts:67), so even a non-interactive install writes a line that discloses its own egress. On the interactive path, any write OR in-place upgrade of the marker (the silent pointer-to-nudge upgrade I flagged, plus dry-run previews) prints a dim sub-line naming what the nudge instructs and that question text leaves the machine (nudgeFilesTouched gating in skillsWalkthrough), and the CLAUDE.md prompt discloses the same egress before asking (decideClaudeMd). That meets the bar the review set (pick a posture, disclose it); tests cover fresh write, silent upgrade, and the no-disclosure-on-untouched-rerun case. The default-write-vs-opt-in choice for AGENTS.md remains a product call the operator can still override, but it is no longer silent.

2 (--json): resolved. The inline example is now tenjin lookup "<question>" --json (install.ts:67), matching the merged #20 machine contract. The closing "Done. Try: tenjin lookup ..." walkthrough suggestion is left un-flagged deliberately and correctly: it renders only on the human TTY path, where human output is what #20 intends.

3 (reversibility): mitigated for a prototype. Every write/update now prints "Undo anytime: delete the <!-- tenjin-cli:skills --> line from ", so the manual undo is discoverable. A first-class tenjin uninstall is explicitly deferred to #21 productionizing; reasonable at this stage.

4 (dual-AGENTS.md drift): accepted. Agreed pre-existing and low-risk, left as-is by mutual note.

One micro-note, not blocking: on a --dry-run interactive install the disclosure block still prints the "Undo anytime: delete ... from " line for a file that was not actually written; the top-of-output "Dry run: nothing was written" covers the context, so this is cosmetic.

No injection content in the delta or comment.

[A1igator]

Product call from the owner: the current consent posture stands as designed. Default-write for the AGENTS.md line (an in-place upgrade of the marker install already owned, now self-disclosing with an undo path) and opt-in for CLAUDE.md (new surface, personal global config, redundant channel for Claude Code). No behavioral change requested.