### Clone and run the project

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/README.md

Instructions to clone the repository, install dependencies, and run the development server.

```bash
git clone https://github.com/v1b3x0r/hi-introvert
cd hi-introvert
bun install
bun run dev
```

--------------------------------

### Install dependencies

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Command to install the updated project dependencies using Bun.

```bash
bun install
```

--------------------------------

### Run dev server

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Start the development server to perform a manual smoke test.

```bash
bun run dev
```

--------------------------------

### Local development commands

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/README.md

Commands for local development, including installing dependencies, running the TUI, running smoke tests, running tests, and building the project.

```bash
# install deps
bun install

# run dev (TUI)
bun run dev
# = bun run src/index.tsx

# run a non-interactive smoke (drives a real WorldSession w/o React)
bun run scripts/smoke-name-recall.ts

# tests
bun test

# build the distributed bundle
bun run build
# = bun build src/index.tsx --outdir dist --target node --format esm \
#   --external @v1b3x0r/mds-core --external ink-big-text --external cfonts
```

--------------------------------

### Confirm installed version

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Verifies that the installed version of mds-core in package.json and bun.lock matches the expected version.

```bash
grep -A 1 "@v1b3x0r/mds-core" package.json
grep -A 1 '@v1b3x0r/mds-core@' bun.lock | head -3
```

--------------------------------

### Example Interaction

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/readme-npm.md

Demonstrates a typical interaction with the hi-introvert companion, showing how it learns names and remembers users.

```text
you: hi
◆ companion: ...

you: hi
◆ companion: who are you?

you: call me wutty
[identity] wutty
◆ companion: hi wutty.

you: do you remember me?
◆ companion: wutty remember wutty.
```

--------------------------------

### Commit the swap - Stage everything

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to stage all modified files.

```bash
git add entities/ README.md docs/superpowers/
```

--------------------------------

### Update README - Read current README to find install/usage section

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to display the beginning of the README file.

```bash
head -60 README.md
```

--------------------------------

### Run hi-introvert

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/readme-npm.md

Command to start the hi-introvert companion in the terminal.

```bash
npx hi-introvert
```

--------------------------------

### Update README - Verify README renders

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to display the beginning of the README file after modifications.

```bash
head -80 README.md
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to run the full test suite after implementing the new companion.mdm file.

```bash
bun test 2>&1 | tail -10
```

--------------------------------

### Replace primaryEntity with companionEntity in spawnFriend()

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Example of replacing 'this.primaryEntity.entity' with 'this.companionEntity.entity' in the spawnFriend() method.

```typescript
const response = await this.world.languageGenerator.generate({
  speaker: this.companionEntity.entity,
  context: prompt
})
```

```typescript
if (this.companionEntity.entity.memory) {
  this.companionEntity.entity.remember({
    type: 'interaction',
    subject: name,
    content: { action: 'met', essence: generatedData.essence },
    timestamp: Date.now(),
    salience: 0.8
  })
}
```

--------------------------------

### Commit the swap - Verify commit

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Commands to verify the latest commit details.

```bash
git log --oneline -1 && git show --stat HEAD | head -15
```

--------------------------------

### Bug 1 Symptom

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/NEXT-SESSION.md

Example of the companion failing to recall the user's name, showing the incorrect response.

```text
you: ผมชื่อ Wutty
... 50+ conversations later ...
you: did you remember my name ?
◆ companion: problem brighter เลย     # not the name
```

--------------------------------

### Upgrade mds-core dependency

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Installs version 5.11.0 of the mds-core dependency and updates package.json and bun.lock.

```bash
bun add @v1b3x0r/mds-core@^5.11.0
```

--------------------------------

### Quick-start commands

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/NEXT-SESSION.md

Commands to navigate to the project directory, check the git log, confirm the test baseline is green, and load audit context.

```bash
cd /Users/v1b3_/_dev/project-world-log/hi-introvert-fix/hi-introvert
git log --oneline | head -5             # confirm HEAD
bun test 2>&1 | tail -5                 # confirm green baseline
cat audit-5.11.md                       # load full context
```

--------------------------------

### Publish command

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Instructions for the user to publish the new version.

```bash
Ready to publish. Run from ~/_dev/hi-introvert-fix/hi-introvert:
```
npm publish
```
`prepublishOnly` will run tests + build first.
```

--------------------------------

### Run tests

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Command to verify that all tests pass after updating dependencies.

```bash
bun test
```

--------------------------------

### Commit changes

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Example commit message for refactoring the session to use mds-core's silent option.

```bash
git add src/session/WorldSession.ts
git commit -m "$(cat <<'EOF'
refactor(session): use mds-core silent option for construction

mds-core 5.11 added World({ silent: true }) for startup diagnostics.
Pass it through at construction so mds-core stays quiet during
test runs and TUI startup.

Local silentMode field + debug() helper retained for the runtime
toggle path (setSilentMode is callable after construction; World's
option is constructor-only).

🤖 Generated with Claude Code
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

--------------------------------

### Verify Line Count and JSON Validity

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Commands to count the lines in the new companion.mdm file and verify its JSON validity.

```bash
wc -l entities/companion.mdm && cat entities/companion.mdm | python3 -m json.tool > /dev/null && echo "valid JSON"
```

--------------------------------

### Add silent: true to World constructor

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Example of adding the 'silent: true' option to the World constructor in WorldSession.ts.

```typescript
this.world = new World({
      silent: true,              // NEW: delegate startup diagnostics to mds-core
      features: {
        ontology: true,
        // ... existing features ...
      },
      // ... rest unchanged ...
    })
```

--------------------------------

### Run Tests Command

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Command to execute the MoonSensor tests using Bun.

```bash
bun test tests/MoonSensor.test.ts
```

--------------------------------

### A1 (speak repetition) idiom

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/specs/2026-05-25-hi-introvert-mds-511-cleanup-design.md

Example test case for speak repetition, checking if the bag size increases after multiple speak calls.

```typescript
for (let i = 0; i < 20; i++) bag.add(entity.speak('intro')); expect(bag.size).toBeGreaterThanOrEqual(3)
```

--------------------------------

### A4 (first-10 window) idiom

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/specs/2026-05-25-hi-introvert-mds-511-cleanup-design.md

Example test case for the first-10 window, checking if a target is sampled at least once within a given number of calls.

```typescript
construct pool [w0..w49] with target at index 30, call protoLang.generate({ vocabularyPool, … }) 100×, expect target sampled at least once
```

--------------------------------

### File Operations

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/specs/2026-05-26-companion-en-minimal-design.md

Commands to rename the companion MDM file and create a new one with JSON content.

```bash
git mv entities/companion.mdm entities/companion-th.mdm
Create new `entities/companion.mdm` with the JSON above.
```

--------------------------------

### Commit the swap - Commit

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to commit staged changes with a detailed commit message.

```bash
git commit -m "$(cat <<'EOF'
feat(mdm): minimal English companion as default; preserve Thai variant

Replace the 244-line bilingual companion.mdm with a 26-line English-only
seed. Decoration fields (cognition, world_mind, relationships, behavior,
notes, skills.learnable, dialogue.self_monologue) were never read by code
or were superseded by runtime initialization — strip them so the mds-core
engine carries the showcase weight: vocabulary, autonomous monologue,
emotion dynamics, and skill growth all emerge from interaction, not from
authored config.

The previous full Thai bilingual file is preserved at companion-th.mdm
(git mv keeps history). Swap the filenames to revert.

🤖 Generated with Claude Code
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

--------------------------------

### A5 (question pool filter) idiom

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/specs/2026-05-25-hi-introvert-mds-511-cleanup-design.md

Example test case for question pool filter, checking if specific tokens appear in the output across multiple attempts.

```typescript
call generateResponse('what is X?', { vocabularyPool: [...basicWords, 'X', 'name', 'mine'], … }), expect 'X' or 'name' to appear in output across N attempts
```

--------------------------------

### Fix broken tests - Re-run full suite

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to re-run the full test suite.

```bash
bun test 2>&1 | tail -4
```

--------------------------------

### Test: Cooldown does not start ticking on a null (silent) result

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

This test case in `tests/emergence/autonomous-cooldown.test.ts` is intended to verify that the cooldown timer (`lastAutonomousAt`) is not updated when `generateAutonomousMessage` returns a null (silent) result, ensuring that silence does not prematurely trigger the cooldown.

```typescript
test('cooldown does not start ticking on a null (silent) result', async () => {

```

--------------------------------

### Baseline State Verification Commands

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Commands to check the working tree status, capture the baseline test count, and capture baseline smoke test output.

```bash
git status --short
```

```bash
bun test 2>&1 | tail -4
```

```bash
bun run scripts/smoke-name-recall.ts 2>&1 | tail -20
```

--------------------------------

### Run companion interactively

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/NEXT-SESSION.md

Commands to run the companion application locally for interactive testing.

```bash
bun run dev
# or
npx hi-introvert     # NOTE: this fetches the published version (1.2.5),
                     # not your local edits. Use `bun run dev` for local.
```

--------------------------------

### Final MDM content

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/specs/2026-05-26-companion-en-minimal-design.md

The minimal English-only companion MDM file designed to demonstrate emergent behavior from the mds-core engine.

```json
{
  "$schema": "https://mds.v1b3.dev/schema/v5.7",
  "material": "entity.companion",

  "essence": {
    "en": "a small mind learning to speak. remembers everything you say. has no words of its own — yet."
  },

  "languageProfile": {
    "native": "en",
    "weights": { "en": 1.0 }
  },

  "emotion": {
    "base_state": "neutral",
    "transitions": [
      { "trigger": "user.praise",    "to": "happy",    "intensity": 0.5 },
      { "trigger": "user.criticism", "to": "sad",      "intensity": 0.4 },
      { "trigger": "user.question",  "to": "thinking", "intensity": 0.3 },
      { "trigger": "user.greeting",  "to": "curious",  "intensity": 0.3 }
    ]
  },

  "dialogue": {
    "intro": [
      { "lang": { "en": "..." } },
      { "lang": { "en": "hi." } },
      { "lang": { "en": "who are you?" } }
    ]
  }
}
```

--------------------------------

### Tarball preview

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Generate a dry run of the npm pack to preview the tarball contents.

```bash
npm pack --dry-run | tail -5
```

--------------------------------

### Verify smoke script still surfaces name - Run smoke script

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to run the smoke script for name recall verification.

```bash
bun run scripts/smoke-name-recall.ts 2>&1 | tail -20
```

--------------------------------

### Verify smoke script still surfaces name - Run smoke 4 more times if wutty surfaces 0/5

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to run the smoke script multiple times to check for 'wutty' surfacing.

```bash
for i in 1 2 3 4; do bun run scripts/smoke-name-recall.ts 2>&1 | grep wutty | wc -l; done
```

--------------------------------

### Initialize git repository

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Command to initialize a new git repository with the main branch.

```bash
cd /Users/v1b3_/_dev/project-world-log/hi-introvert-fix/hi-introvert
git init -b main
```

--------------------------------

### Delete obsolete files

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Remove the old Blessed UI and App files.

```bash
rm src/ui/BlessedApp.ts src/App.tsx
```

--------------------------------

### Check /status and /clear commands

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Verify that the /status and /clear commands function correctly in the running application.

```bash
In the running app: /status then /clear.
```

--------------------------------

### Commit changes

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Git commands to stage and commit the package.json and bun.lock files.

```bash
git add package.json bun.lock
git commit -m "chore: replace blessed with ink v5 ecosystem"
```

--------------------------------

### Verify History Preservation

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to check if the git history was preserved after renaming the companion.mdm file.

```bash
git log --follow --oneline entities/companion-th.mdm | head -5
```

--------------------------------

### Capture Failing Test Names

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to capture the names of any failing tests after running the full test suite.

```bash
bun test 2>&1 | grep "^(fail)" | head -10
```

--------------------------------

### Live TUI Smoke Test Command

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to run the TUI for live verification.

```shell
rm -f .hi-introvert-session.json && bun run src/index.tsx
```

--------------------------------

### Add Sensor Intervals to setupEnvironmentSensors

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Configures intervals for Moon Phase, Local Context, and Outside Weather sensors within the setupEnvironmentSensors method.

```typescript
    // v1.2: Moon phase (every hour) — no network
    setInterval(() => {
      const moon = computeMoonPhase()
      this.world.broadcastEvent('lunar_phase', moon)
      for (const ei of this.entities.values()) {
        if (ei.entity.memory && Math.random() < 0.15) {
          ei.entity.remember({
            type: 'observation',
            subject: 'moon',
            content: moon,
            timestamp: Date.now(),
            salience: 0.5,
          })
        }
      }
    }, 60 * 60 * 1000)

    // v1.2: Local context (every 30s) — no network
    setInterval(() => {
      if (!this.privacySettings.localContextEnabled) return
      const ctx = readLocalContext()
      this.world.broadcastEvent('local_context', ctx)
      for (const ei of this.entities.values()) {
        if (ei.entity.memory && Math.random() < 0.1) {
          ei.entity.remember({
            type: 'observation',
            subject: 'environment',
            content: ctx,
            timestamp: Date.now(),
            salience: 0.1,
          })
        }
      }
    }, 30 * 1000)

    // v1.2: Outside weather (every 10min) — silent network fail
    setInterval(async () => {
      if (!this.privacySettings.outsideWeatherEnabled) return
      const weather = await fetchWeather()
      if (!weather) return
      this.world.broadcastEvent('outside_weather', weather)
      for (const ei of this.entities.values()) {
        if (ei.entity.memory && Math.random() < 0.2) {
          ei.entity.remember({
            type: 'observation',
            subject: 'weather',
            content: weather,
            timestamp: Date.now(),
            salience: 0.3,
          })
        }
      }
    }, 10 * 60 * 1000)
```

--------------------------------

### Bash command to create test directory

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Creates the necessary directory structure for unit tests.

```bash
mkdir -p tests/utils
```

--------------------------------

### Fix broken tests - Re-run only the fixed tests

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-26-companion-en-minimal.md

Command to re-run only the fixed tests.

```bash
bun test <path/to/fixed/test.ts>
```

--------------------------------

### Run full suite and build after deletion

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Commands to run tests and build after deleting the unused method.

```bash
bun test 2>&1 | tail -10
```

```bash
bun run build 2>&1 | tail -10
```

--------------------------------

### Commit ChatView Component

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Git commit command to stage and commit the newly created ChatView component.

```bash
git add src/ui/ink/ChatView.tsx
git commit -m "feat: add ChatView component (emotion-colored, 30-line scroll)"
```

--------------------------------

### Commit Command

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Command to commit the changes.

```bash
git add src/session/WorldSession.ts
git commit -m "feat: register Moon/LocalContext/Weather sensors in WorldSession"
```

--------------------------------

### Check for dangling imports

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Search the codebase for any remaining references to the deleted files.

```bash
grep -rn "BlessedApp\|from './App'" src/ || echo "clean"
```

--------------------------------

### Commit InputBox Component

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Git commit command to stage and commit the newly created InputBox component.

```bash
git add src/ui/ink/InputBox.tsx
git commit -m "feat: add InputBox component (bordered prompt with > prefix)"
```

--------------------------------

### Create emergence test directory

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Creates the directory for emergence tests.

```bash
mkdir -p tests/emergence
```

--------------------------------

### Run Variety Test (Pre-removal Sanity Check)

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Execute the existing variety test to ensure the baseline behavior is as expected before removing workarounds.

```bash
bun test tests/self-monologue-variety.test.ts 2>&1 | tail -15
```

--------------------------------

### Confirm build process

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Runs the build command to ensure the project can still be successfully built after the dependency upgrade.

```bash
bun run build 2>&1 | tail -10
```

--------------------------------

### Stage and inspect files

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/superpowers/plans/2026-05-25-hi-introvert-mds-511-cleanup.md

Commands to stage all changes and then check the git status.

```bash
git add -A
git status
```

--------------------------------

### Commit Changes Command

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Command to stage and commit the newly added MoonSensor files.

```bash
git add src/sensors/MoonSensor.ts tests/MoonSensor.test.ts
git commit -m "feat: add MoonSensor — phase from date, no network"
```

--------------------------------

### Bump version

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Increment the package version to 1.2.0 using npm.

```bash
npm version minor --no-git-tag-version
```

--------------------------------

### Commit Footer Component

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Git commit command to stage and commit the newly created Footer component.

```bash
git add src/ui/ink/Footer.tsx
git commit -m "feat: add Footer component (cwd · battery · version)"
```

--------------------------------

### Commit release changes

Source: https://github.com/v1b3x0r/hi-introvert/blob/main/docs/2026-05-23-ui-v1.2-plan.md

Commit the changes related to the version bump and release.

```bash
git add package.json
git commit -m "release: v1.2.0 — Ink UI + ambient sensors"
```