Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

docs: sync documentation with notfair 0.9.8

Yuting Zhong2fdebefbe80a
diff --git a/notfair/ARCHITECTURE.md b/notfair/ARCHITECTURE.md
index ce1f7378..6e6f1cb1 100644
--- a/notfair/ARCHITECTURE.md
+++ b/notfair/ARCHITECTURE.md
@@ -74,7 +74,8 @@ USER'S MACHINE
disposable; the DB is the loop's memory.
4. One adapter turn runs on a `tick-<n>` session; every event persists to
`transcript_events`; the result lands as a `goal_ticks` diary row the
- dashboard renders (and links to the full transcript).
+ dashboard renders. Opening that row resumes the same chat session, so a
+ completed check remains available for follow-up turns in its original context.
Chat turns hit the same agent through `/api/chat` — same identity, same
rules; anything decided in chat that future ticks must know is written to
diff --git a/notfair/CLAUDE.md b/notfair/CLAUDE.md
index dea790a7..cbc2a1bb 100644
--- a/notfair/CLAUDE.md
+++ b/notfair/CLAUDE.md
@@ -22,8 +22,10 @@ This repo carries no migrations or legacy/compat code. Verification is:
node; component tests opt into a DOM with a leading
`// @vitest-environment jsdom` pragma and use `@testing-library/react`.
Mock at the server-action / db-module boundary (`vi.mock`), not deeper.
- Test pure logic and user-visible component behavior — don't unit-test
- Next.js pages or route handlers; the live smoke covers those.
+ Test pure logic and user-visible component behavior. Prefer testing below
+ the page boundary, but use a focused page regression test when the bug is
+ in server-page wiring that lower-level tests cannot observe. Route handlers
+ normally stay covered by the live smoke.
SQLite tests use the real better-sqlite3 against a tmpdir — and the
`NOTFAIR_DATA_DIR` override MUST be set inside `vi.hoisted(...)`:
static imports evaluate before module-level statements, so a plain
diff --git a/notfair/CONTRIBUTING.md b/notfair/CONTRIBUTING.md
index 2c32b189..09ecb5d5 100644
--- a/notfair/CONTRIBUTING.md
+++ b/notfair/CONTRIBUTING.md
@@ -102,7 +102,7 @@ See `ARCHITECTURE.md`. Short version:
- Default environment is node; component tests opt into a DOM with a leading `// @vitest-environment jsdom` pragma and use `@testing-library/react`.
- Mock at the server-action / db-module boundary (`vi.mock`), not deeper.
- SQLite tests run the real `better-sqlite3` against a tmpdir. The `NOTFAIR_DATA_DIR` override MUST be set inside `vi.hoisted(...)` — static imports evaluate before module-level statements, so a plain assignment would point the suite at your live `~/.notfair`.
-- Test pure logic and user-visible component behavior; don't unit-test Next.js pages or route handlers — the live smoke covers those.
+- Test pure logic and user-visible component behavior. Prefer testing below the page boundary, but use a focused page regression test when the bug is in server-page wiring that lower-level tests cannot observe. Route handlers normally stay covered by the live smoke.
## Commits + PRs
diff --git a/notfair/README.md b/notfair/README.md
index 5077ee66..681a755b 100644
--- a/notfair/README.md
+++ b/notfair/README.md
@@ -12,7 +12,7 @@ Open source. Runs entirely on your machine. Bring your own LLM credentials (via
- **Fully autonomous, visibly so.** No approval inbox — agents are instructed to act inside the spend envelope you set, with observation-window discipline, a pause button for scheduled work, and their recorded moves visible in the app. These are workflow controls for a trusted harness, not a sandbox against arbitrary local commands.
- **Code changes through pull requests.** Attach a GitHub-backed codebase and an agent can work in its own branch, commit and push the change, then register the pull request with NotFair. The app tracks the PR, while its goal protocol instructs the agent to leave merge decisions to you and keep one code mutation in flight at a time. Those rules are prompt-level guardrails, not mechanically enforced permissions.
- **Shared context + private memory.** `PROJECT.md` is the workspace brief every agent carries (any agent can update it via `set_shared_context`); each agent also keeps its own learnings ledger and workspace files. All connected MCPs are shared by every agent.
-- **One screen per goal.** The conversation and the loop's state live together: chat on the left (where the goal is defined and steered), a status rail on the right — the progress chart, the plan, every check with its full log, open actions with review dates, and the agent's memory. No tabs, no thread management, nothing else to learn.
+- **One screen per goal.** The conversation and the loop's state live together: chat on the left (where the goal is defined and steered), a status rail on the right — the progress chart, the plan, every check with its own follow-up chat, open actions with review dates, and the agent's memory. No tabs, no thread management, nothing else to learn.
- **Progress you can see.** A time-true chart with the target line, every agent action as a marker on the moment it happened (hover: what it did, what it predicted, what actually happened), observation windows shaded, and history backfilled at setup from the platform's own date-segmented stats — context from day one. Maintain goals get a streak ("held at target for 12 days") with a per-check strip; the workspace index shows a mini sparkline + 7-day delta per goal.
- **Project-scoped MCP connections** — one-click PKCE OAuth brings third-party tools (Google Ads via NotFair's hosted MCP) into the agents' toolbox. Connection records are stored in local SQLite and wired into the chosen harness automatically; Codex receives bearer tokens through per-server environment variables at process launch.
@@ -87,7 +87,7 @@ When autostart is enabled, launchd owns the server: `notfair start` delegates to
1. You type a goal statement and can select its platform focus. NotFair creates the goal row (status `intake`), provisions an anonymous goal agent, and creates its workspace at `~/.notfair/agents/<agent-id>/`. The goal protocol is mirrored into the harness's native config (`CLAUDE.md` / `AGENTS.md`, `.mcp.json` for Claude Code, sections in `~/.codex/config.toml` for Codex), with the project's connected MCPs wired in.
2. You chat while the agent records the ambition (`define_goal`), authors and tests a metric query, submits it (`propose_goal_metric` — the platform re-runs it server-side and stores the measured baseline), then proposes the measured target. When you confirm in chat, the agent records the agreement (`propose_target`) — the goal goes active and the first tick runs immediately.
-3. The heartbeat rides a `setInterval` in the Next.js process polling every 30 seconds. Due goals get a tick: the metric is measured, a brief is composed from the database, one adapter turn runs, and the diary row is written. A completed check opens as a static log instead of remaining in a streaming state.
+3. The heartbeat rides a `setInterval` in the Next.js process polling every 30 seconds. Due goals get a tick: the metric is measured, a brief is composed from the database, one adapter turn runs, and the diary row is written. A completed check shows a static terminal status but keeps its composer active, so follow-up turns continue in that check's original session.
## Code changes through pull requests