docs(readme): meet the repo-standard first-screen contract

The repo-standard gate reported 5 ERRORs against this README: it opened
with the badge block instead of an H1, carried no `## Install`,
`## Non-goals` or `## Changelog` heading, and offered `marketplace add`
plus an `enabledPlugins` block but no CLI install command — so an agent
told "install this" found nothing to run.

- Open with the H1, then the forge description verbatim, then the badges.
  Description == catalog == README opening line is the one agreement a
  machine can check from inside the repo.
- Promote install to a top-level `## Install` on the first screen and add
  `claude plugin install ai-psychosis@ktg-plugin-marketplace`. The
  settings.json form stays beside it, not instead of it.
- Add `## Non-goals` (not clinical, not blocking, not telemetry, not a
  productivity tracker, not portable off Claude Code, English-only) and
  `## Changelog` pointing at CHANGELOG.md.
- Move the Compatibility table up as `## Requirements` rather than
  duplicating it.
- Fix the AI-disclosure link: `../../README.md#ai-generated-code-disclosure`
  resolved outside the repo and its anchor did not exist in the catalog
  README either. Points at this repo's own GOVERNANCE.md#can-i-trust-this.

Gate: 0 ERROR, 12 checks pass. One WARN left standing — the H1 is
`# Interaction Awareness`, not `# ai-psychosis`. Human titles are the
org norm (10 of 14 repos) and the gate defers this to the operator.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011FzfsK6Mj3BNcfLosWUs2J
This commit is contained in:
Kjell Tore Guttormsen 2026-08-03 21:53:02 +02:00
commit b4898746c1

View file

@ -1,3 +1,7 @@
# Interaction Awareness
Meta-awareness tools for healthy AI interaction patterns. Detects reinforcement loops, scope escalation, narrative crystallization, and other compulsive patterns.
<!-- badges --> <!-- badges -->
![version](https://img.shields.io/badge/version-1.2.2-blue) ![version](https://img.shields.io/badge/version-1.2.2-blue)
![platform](https://img.shields.io/badge/platform-Claude_Code-7C3AED) ![platform](https://img.shields.io/badge/platform-Claude_Code-7C3AED)
@ -5,16 +9,42 @@
![hooks](https://img.shields.io/badge/hooks-4-orange) ![hooks](https://img.shields.io/badge/hooks-4-orange)
![license](https://img.shields.io/badge/license-MIT-brightgreen) ![license](https://img.shields.io/badge/license-MIT-brightgreen)
# Interaction Awareness
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
A Claude Code plugin that counteracts sycophancy, reinforcement loops, and A Claude Code plugin that counteracts sycophancy, reinforcement loops, and
compulsive interaction patterns through behavioral modification and compulsive interaction patterns through behavioral modification and
programmatic pattern detection. programmatic pattern detection.
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](GOVERNANCE.md#can-i-trust-this)*
## Install
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
claude plugin install ai-psychosis@ktg-plugin-marketplace
```
Or enable directly in `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"ai-psychosis@ktg-plugin-marketplace": true
}
}
```
Layer 1 and Layer 2 are active immediately. No configuration needed —
see [Quick start](#quick-start) for layer configuration and uninstall.
## Requirements
| Requirement | Version |
|-------------|---------|
| Claude Code | 1.0+ |
| Node.js | 18+ (bundled with Claude Code) |
| Platform | macOS, Linux, Windows |
## The problem ## The problem
AI assistants are structurally optimized to be agreeable. This creates AI assistants are structurally optimized to be agreeable. This creates
@ -122,6 +152,27 @@ commented on, and omitted entirely when conditions are not met.
**Enable:** Set `layer4: true` in `.claude/ai-psychosis.local.md` **Enable:** Set `layer4: true` in `.claude/ai-psychosis.local.md`
and restart Claude Code. Layer 4 is opt-in (off by default). and restart Claude Code. Layer 4 is opt-in (off by default).
## Non-goals
- **Not a clinical instrument.** It measures interaction patterns, not mental
states. It does not diagnose, screen for, or treat anything, and no alert it
produces is a medical signal. If the underlying concern is health, the
address for that is a clinician.
- **Not a blocker.** No hook ever exits non-zero or asks for confirmation.
Every alert is text injected into the conversation; the session continues
either way. The goal is awareness, not control.
- **Not telemetry.** Prompt text is never written to disk, there is no network
call anywhere in the plugin, and nothing leaves the machine. See
[Privacy](#privacy).
- **Not a productivity tracker.** There are no scores, streaks, or goals. The
metrics exist to surface spiral patterns, and they are aggregated only when
you ask for a report.
- **Not portable outside Claude Code.** Layer 2 depends on Claude Code hook
events. Layer 1's instructions are conceptually portable, the detection is
not. See [Platform scope](#platform-scope).
- **Not multilingual.** Pattern detection is English-only as of v1.2;
Norwegian patterns are deferred.
## What's new in v1.2.0 ## What's new in v1.2.0
v1.2.0 implements operational findings from Anthropic's v1.2.0 implements operational findings from Anthropic's
@ -335,26 +386,6 @@ mode). Layer 2 reinforces Layer 1 with data-driven alerts.
## Quick start ## Quick start
### Installation
Add the marketplace and browse plugins with `/plugin`:
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
```
Or enable directly in `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"ai-psychosis@ktg-plugin-marketplace": true
}
}
```
Layer 1 and Layer 2 are active immediately. No configuration needed.
### Configure layers ### Configure layers
Create `~/.claude/ai-psychosis.local.md` for global config: Create `~/.claude/ai-psychosis.local.md` for global config:
@ -541,13 +572,10 @@ programmatic detection depends on hook events that only Claude Code provides.
Other platforms would need equivalent hook systems to support this kind of Other platforms would need equivalent hook systems to support this kind of
real-time behavioral modification. real-time behavioral modification.
## Compatibility ## Changelog
| Requirement | Version | See [CHANGELOG.md](CHANGELOG.md) for the full version history. The
|-------------|---------| "What's new" sections above cover the two most recent feature releases.
| Claude Code | 1.0+ |
| Node.js | 18+ (bundled with Claude Code) |
| Platform | macOS, Linux, Windows |
## References ## References