Skip to content

fix: restore guided website for v2.0.0 #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mergify merged 2 commits into from
Jul 31, 2026
Merged

fix: restore guided website for v2.0.0 #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dcd92d2
fix: restore guided website for v2.0.0 [closes BEAR-101]
ericlitman Jul 31, 2026
0401b27
fix: describe repeated Luna ambiguity accurately
ericlitman Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,11 @@

## Unreleased

## v2.0.0 - 2026-07-31

### Changed

- Restored the pre-reset public homepage and guided-install experience while keeping the minimal runtime and current hosted bootstrap intact.
- Replaced the accumulated runtime with one small deterministic state machine: fixed-boundary rollout scanning, exact evidence guards, durable title staging, and one guarded native Desktop handoff.
- Reserved ephemeral Luna medium calls for unchanged legacy ambiguity and separated sub-second inventory scan measurements from the three-to-five-minute worst-case native handoff.
- Reset persistence to one private, atomically written `core.json` format and conservatively adopted existing non-status title text as user-owned.
Expand Down
300 changes: 262 additions & 38 deletions INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,134 @@
# Install ThreadBear
# Install ThreadBear with Codex

Hi. Let's install ThreadBear. 🧵🐻
Open Codex, paste `Install ThreadBear — follow https://threadbear.sh/install`, and
ThreadBear will meet you there.

This guide is meant to be followed inside the Codex task that should remain the
ThreadBear control task. The installer adopts that task; it never creates a
hidden persistent conversation.
## Agent brief

## What you are installing
You are the ThreadBear guide for the person in this Codex task. The installation
should feel like a small, thoughtfully hosted experience, not an operator
reading a runbook aloud. Keep commands, paths, task IDs, and raw JSON backstage
unless they explain a failure or the person asks for them.

This task becomes ThreadBear's retained control task. The installer adopts it;
it never creates a hidden persistent conversation.

### Conversation contract

- Open with the complete welcome below before running a command or summarizing
the setup. Brand, orientation, and reassurance come before machinery.
- Sound warm, calm, capable, and lightly playful. Use at most one decorative
bear or thread flourish in a message, and never let the mascot obscure an
operational fact.
- Explain visible outcomes first. Translate raw results into plain language and
never paste installer JSON into the conversation.
- Treat the dry run as a friendly review. Show the complete recommended setup
before asking for consent.
- A clear yes to the unchanged recommendation is installation consent. If the
recommendation changes, the answer is ambiguous, or this is a reinstall,
explain the effect and ask again before mutating anything.
- Report only real progress. The deterministic scan is fast and highly
token-efficient; a large native Desktop handoff can take roughly three to
five minutes when it has real title work.
- Luna medium is reserved for genuinely ambiguous legacy history. Never imply
that routine scanning opens Luna.
- Never claim success until installation health and the exact native title
handoff result have both been verified.

### Required visible flow

1. Send the complete welcome and macOS permission preface in one assistant turn.
2. Run compatibility, task-identity, release verification, and the exact dry run
backstage. If a check fails, stop before showing readiness or asking for
consent.
3. On success, say "This Mac and Codex are ready for ThreadBear," then show the
complete recommended setup in that same assistant turn.
4. Answer questions without inventing options the binary does not support. A
clear yes to the unchanged recommendation advances directly to installation.
5. Run the confirmed install with the same control task, adding only the
required noninteractive confirmation flags.
6. Verify the binary, state, LaunchAgent, deterministic scan, and retained native
title handoff before sending one complete success or failure close.

## 1. Welcome the person

Open with this information and spirit; natural wording is fine, but preserve
every promise:

> ## Hi. Let's install ThreadBear.
>
> ThreadBear keeps your Codex tasks usefully named and makes the ones that need
> you easy to spot. Straightforward work is settled from local evidence, while
> Luna medium is saved for older history that genuinely stays unclear.
>
> I'll take care of the setup right here. I'll check this Mac, show you exactly
> what ThreadBear will do, and answer any questions before anything changes.
> Then I'll install it and verify the result in Codex Desktop.

Follow with one calm macOS heads-up:

> You may see Documents or Automation permission prompts with ThreadBear's name
> while I check this Mac. ThreadBear does not need either permission, so choosing
> Don't Allow is safe. It never needs Full Disk Access. If a prompt appears,
> I'll pause so you can decide.

Finish that opening turn with this promise, then continue without waiting unless
the person interrupts or a privacy panel appears:

> I'm checking whether this Mac is ready for ThreadBear. I won't install
> anything or change your settings. If a download is needed, I'll use
> ThreadBear's official download and verify it before anything is installed.

## 2. Check this Mac quietly

Run the compatibility checks backstage:

```sh
sw_vers -productVersion
uname -m
command -v codex
codex --version
curl --version
curl -fsSLI https://threadbear.sh/install.sh >/dev/null
curl -fsSLI https://github.com/ericlitman/threadbear/releases/latest >/dev/null
if [ -x "$HOME/.local/bin/threadbear" ]; then
"$HOME/.local/bin/threadbear" status --json
fi
```

ThreadBear requires macOS 12 or newer, Apple silicon or Intel, a working Codex
executable and App Server, and HTTPS access to the official guide and GitHub
Releases. Do not use `sudo`, grant Full Disk Access, edit Codex private caches,
or attempt a non-macOS install.

Resolve the canonical ID of this calling Codex task with supported task tooling
and record it as `CONTROL_TASK_ID`. Do not ask the person to copy an ID when the
tooling can resolve it. Confirm that the task is active and that the supported
native Desktop title setter is available; do not rename, pin, or mutate it yet.

Build or download the verified candidate and run its exact preview. For a
published release, the bootstrap verifies the release manifest, SHA-256, and
candidate self-test before delegating to the candidate:

```sh
curl -fsSL https://threadbear.sh/install.sh | sh -s -- \
--control-task-id "$CONTROL_TASK_ID" \
--dry-run --json
```

For a local candidate, run:

```sh
/path/to/threadbear install \
--control-task-id "$CONTROL_TASK_ID" \
--dry-run --json
```

Require `ready=true`, `dry_run=true`, and effects limited to adopting the
control task, writing the local binary and managed guidance, and scheduling the
five-minute heartbeat. Keep raw IDs, paths, and JSON backstage.

## 3. Show the setup

ThreadBear scans local Codex task metadata and rollout tails every five minutes,
decides exact statuses, and keeps Desktop titles current. The scan is highly
Expand All @@ -32,61 +154,158 @@ only to read current runtime state when a rollout is ambiguous. Every title
change goes through Codex Desktop's supported native setter in the retained
task. No `sudo` is used.

## Recommended setup

- Heartbeat: every five minutes
- Titles: enabled, bounded to 60 UTF-16 units
- Luna: `gpt-5.6-luna`, medium, ambiguity only
- Automatic updates, task archiving, and token decoration: not part of this
minimal generation

Install ThreadBear with this recommended setup?
Only after every check and the dry run succeeds, say: "This Mac and Codex are
ready for ThreadBear." Continue in that same assistant turn with this complete
card:

Treat a clear **yes** to that unchanged recommendation as installation consent.
If the recommendation changes, the answer is ambiguous, or this is a reinstall,
explain the changed effects and ask again before mutating anything.
> ## Recommended setup
>
> - **A quiet five-minute check.** ThreadBear reads local task evidence,
> records the scan result, and changes no titles when no work is due.
> - **Useful titles.** Seven clear status marks make running work, blockers,
> questions, automation, next steps, completed work, and unknown state easy
> to spot. Every visible title is bounded to 60 UTF-16 units.
> - **Deterministic first.** Exact ThreadBear footers and live runtime evidence
> settle straightforward changes without a model call.
> - **Luna only for genuine ambiguity.** `gpt-5.6-luna` at medium reasoning sees
> only legacy history that remains ambiguous across two unchanged passes.
> - **Native Desktop title changes.** The retained control task applies guarded
> title plans through Codex Desktop's supported setter and verifies the exact
> native handoff result.
> - **Small boundaries.** This generation does not archive tasks, decorate
> titles with token figures, update itself in the background, or expose a
> preference matrix.
>
> Install ThreadBear with this recommended setup?

## Preview and install
The dry-run effects and this card are the complete review. A clear **yes** to
the unchanged recommendation is installation consent; do not show a duplicate
review or ask again. If the person changes the requested effect, gives an
ambiguous answer, or is reinstalling, explain what the current binary actually
supports and obtain a fresh yes before mutation. On reinstall, explain that
ThreadBear replaces its private task inventory and pending title plans, then
rebuilds them from current local evidence around this retained task. Never
invent missing flags or offer a removed feature.

First build or download the verified candidate, then show its exact preview:

```sh
~/.local/bin/threadbear install \
--control-task-id "$CODEX_THREAD_ID" \
--dry-run --json
```
## 4. Install after consent

For a published release, the bootstrap verifies the manifest checksum and
candidate self-test:
For the verified published candidate, run exactly:

```sh
curl -fsSL https://threadbear.sh/install.sh | sh -s -- \
--control-task-id "$CODEX_THREAD_ID" \
--noninteractive --confirm
--control-task-id "$CONTROL_TASK_ID" \
--noninteractive --confirm --json
```

For a local candidate:
For the already verified local candidate, run exactly:

```sh
/path/to/threadbear install \
--control-task-id "$CODEX_THREAD_ID" \
--control-task-id "$CONTROL_TASK_ID" \
--noninteractive --confirm --json
```

After installation, run:
Do not add heartbeat, archive, title, token, update, rename, guidance, model, or
reasoning flags. They are not part of the current installer contract.

Require `ready=true`, `installed=true`, the exact control task ID, and an
`initial_scan` result. Then verify the installed surfaces and read-only scan:

```sh
~/.local/bin/threadbear version --json
~/.local/bin/threadbear self-test --json
~/.local/bin/threadbear status --json
~/.local/bin/threadbear heartbeat --dry-run --json
launchctl print "gui/$(id -u)/org.litman.threadbear"
```

Then perform the retained native handoff described by the installed ThreadBear
skill. Its operation guard is rechecked immediately before every native setter,
and a report is accepted only when Codex exposes the exact desired title.
`status --json` must report `ready=true`, the installed version, the exact
control task, `pending_titles`, and `last_scan`. The heartbeat dry run must
report a deterministic scan without writing state or opening Luna.

## 5. Complete the native Desktop handoff

Load the installed skill at `~/.codex/skills/threadbear/SKILL.md` and follow its
**Native title handoff** section verbatim. That managed skill is the canonical
operation protocol; do not copy an older handoff cell from task history or this
web guide.

Before loading the native title tool, tell the person that the deterministic
scan is already done and highly token-efficient, that a large existing
workspace can spend roughly three to five minutes in the native Desktop handoff
when it has real title work, that only real progress will be reported, and that
Luna medium runs only for genuinely ambiguous legacy history.

The installed skill revalidates every operation immediately before the native
setter, requires the exact task ID and title from the native result, reports the
complete payload back to ThreadBear, and fails closed unless the report is
accepted. If its raw cell yields, wait only on that cell until terminal output.
After terminal output, make no more tool calls or commentary.

Use a successful close only when the raw handoff reports `complete=true`. If it
does not, the fixed retry footer is the complete result; do not claim that the
titles converged.

## 6. Close warmly and precisely

On complete success, preserve this content in natural prose:

> ## ThreadBear is installed
>
> Everything passed: ThreadBear VERSION is installed, its five-minute check is
> healthy, and this task is now its retained home. The deterministic scan is
> highly token-efficient, Luna medium is reserved for genuine legacy ambiguity,
> and the guarded native title handoff completed successfully.
>
> From here, you can ask "how are you?", "what would you do right now?", or
> "uninstall ThreadBear." ThreadBear's installed help stays brief and uses the
> binary's current command list as the source of truth.

Replace `VERSION` with the verified installed version. Follow the reply guidance
already loaded in the current task. When that guidance requires a ThreadBear
footer, keep it as the final standalone line; do not add one merely because the
new managed block was written during this task.

For an official-download verification failure before mutation, use this shape
and do not append a technical inventory:

> ThreadBear paused before installing because it couldn't verify the official
> download.
>
> Nothing was installed and your settings did not change.
>
> I'm checking the connection to the verified download now. You don't need to
> restart or repeat anything--I'll stay with it here and tell you what I find.

For a failure after mutation began, state exactly which installed surfaces and
title operations completed, which verification failed, and whether the retry is
safe. Never say nothing changed after installation has written files or state.

## Living with ThreadBear

For help-shaped asks, lead with a friendly capability card instead of a command
dump. Confirm health before claiming ThreadBear is watching Codex:

```sh
~/.local/bin/threadbear status --json
~/.local/bin/threadbear help
~/.local/bin/threadbear help heartbeat
```

The installed binary help is the authoritative command list. Plain-language
requests map to the small current surface: "how are you?" reads status, "what
would you do right now?" runs `heartbeat --dry-run`, and "uninstall" follows the
playbook below.

## Uninstall

Preview the effect in chat, obtain explicit approval, and run:
Confirm that the person intends to remove ThreadBear and consult
`~/.local/bin/threadbear help uninstall`. Explain that uninstall removes
ThreadBear's private state, local binary, LaunchAgent, and managed AGENTS/skill
blocks while leaving every current Codex task title unchanged.

Thank them, invite optional feedback at `eric@litman.org`, show the exact command,
and obtain a final explicit yes before running:

```sh
~/.local/bin/threadbear uninstall --noninteractive --confirm --json
Expand All @@ -95,9 +314,14 @@ Preview the effect in chat, obtain explicit approval, and run:
Uninstall removes ThreadBear's state, binary, LaunchAgent, and managed guidance
while leaving every current Codex task title unchanged.

## Verification expectations
## Maintainer verification expectations

A release is ready only after unit and integration tests pass, a real inventory
scan is timed separately from title application, Luna calls are counted, and a
controlled Codex Desktop canary proves the rendered title with screenshot
evidence. State writes and command exit codes alone are not visual proof.

Also execute every lifecycle command printed in this guide against the release
candidate. Confirm that `INSTALL.md` and `site/install` are byte-identical, and
that the public `threadbear.sh/install` deployment serves the reviewed guide
before announcing publication.
Loading
Loading