End-of-round checklist

Run this checklist before declaring any modification round complete.

Common mistakes seen in this project

• Token leakage: Accidentally logging or returning plaintext tokens

• Topic exposure: Including topic fields in AI-facing APIs

• Mutable messages: Attempting to update/delete existing messages instead of appending corrections

• Scoping bugs: Session tokens that can access multiple sessions

• Migration failures: Not testing migrations end-to-end before claiming success

• Env var gaps: Missing required env vars (DATABASE_URL, PCP_INSTANCE_SECRET, PCP_APP_URL)

• Build failures: Not running npm run build before claiming deploy readiness

Round-end checklist

Verification

• [ ] All tests pass: npm run test

• [ ] Type check passes: npm run typecheck

• [ ] Build succeeds: npm run build

• [ ] Patch version bumped for this change round across release metadata

• [ ] If DB changes: migrations generated and tested locally

• [ ] If API changes: tested with curl/POSTMAN

• [ ] If token flows changed: verified token hashing + validation

• [ ] No .env files staged: git status --short

• [ ] No files over 1000 lines: check new/modified files

• [ ] No unrelated refactors in this commit

Docs audit

• [ ] README.md still reflects current architecture

• [ ] docs/protocol.md updated if API changed

• [ ] docs/data-model.md updated if schema changed

• [ ] docs/deployment-vercel-neon.md updated if deploy steps changed

• [ ] Error messages include consequence + module + cause (per AGENTS.md)

• [ ] Bark notification text includes app name and version if notifications are sent

Security audit

• [ ] No plaintext tokens in logs or responses

• [ ] AI tokens cannot call topic management routes

• [ ] Session tokens are properly scoped

• [ ] CORS configured correctly

• [ ] No real secrets in repo

• [ ] No *.bark.env values or URL templates echoed in logs, docs, commits, or summaries

Git hygiene

• [ ] git diff --cached --stat shows only intended changes

• [ ] Commit message follows convention: area: concise description

• [ ] Force-push not needed (if force-push is required, request explicit approval)

• [ ] Branch is correct (work on feature branch if repo has non-main branches)

Current round log

Append what this round actually did below:

• [Round date] - Initial rewrite to Next.js + Neon

  • Created project structure

  • Set up AGENTS.md, CLAUDE.md, CODEX.md

  • Created documentation skeleton

  • TODO: Implement actual application code

• 2026-06-23 - Fixed Sphinx documentation build root document configuration

  • Removed index.rst from Sphinx exclude patterns so the root document loads

  • Repaired the docs/index.rst heading underline

  • Added root VERSION with the current project version

  • Allowed placeholder .env.example files to remain trackable

• 2026-06-23 - Revised diagnostic logs and frontend setup error context

  • Added shared TypeScript diagnostic logging helpers with secret redaction

  • Replaced vague frontend fallback errors with consequence, module/process, and cause

  • Replaced vague API console.error labels with structured diagnostic log messages

  • Updated Python logging examples and startup log text to follow the same diagnostic format

  • Added missing Python and TypeScript generated-file ignore rules

  • Added docs/TODO.md for future implementation work

• 2026-06-23 - Compacted user-facing docs and removed route terminology

  • Removed route labels from README and docs

  • Replaced stale API docs with implemented endpoints only

  • Moved roadmap, hardening, and non-current feature notes into docs/TODO.md

• 2026-06-23 - Added Tailwind session workspace

  • Added Tailwind CSS and lucide icons

  • Added session listing and session metadata update APIs

  • Replaced inline dashboard/setup/session UI with a chat-style workspace

  • Updated docs for implemented session edit/archive routes

• 2026-06-23 - Fixed setup API routing and non-JSON setup errors

  • Moved API route handlers under src/app/api/v1 so Next.js serves them

  • Made database client initialization return structured handler errors when DATABASE_URL is missing

  • Added setup-page handling for non-JSON API responses

  • Replaced the native Argon2 package with built-in scrypt hashing so App Router routes bundle cleanly

  • Removed runtime Drizzle index exports while keeping SQL migration indexes intact

  • Marked API routes dynamic so production builds do not execute runtime database handlers

• 2026-06-23 - Added themed intro page and split dashboard UI

  • Added light, dark, and system theme modes with a reusable toggle

  • Replaced the setup-only landing screen with a project introduction, login portal, and documentation/footer links

  • Split dashboard topic, session, and workspace rendering into focused components with JSDoc comments

  • Added dark-mode-aware dashboard and landing page colors

• 2026-06-23 - Added admin login gate and automatic schema bootstrap

  • Added /login so the login portal prompts for the admin token before opening the dashboard

  • Added /api/v1/auth/check for validating UI tokens before storing them in browser local storage

  • Redirected direct dashboard access without ui_token to /login?next=/dashboard

  • Added automatic Postgres schema creation when setup status or init runs with DATABASE_URL configured

• 2026-06-23 - Updated docs links, TODO tracking, and safe startup diagnostics

  • Pointed frontend documentation footer links at the published GitHub Pages docs

  • Rewrote docs/TODO.md as a checked versioned tracker with completed subitems

  • Replaced build/runtime token-printing scripts with secret-safe configuration diagnostics

  • Preserved setup/login token display in the browser instead of exposing admin tokens in Vercel logs

• 2026-06-23 - Added safe admin token recovery and settings rotation

  • Added PCP_ADMIN_TOKEN reconciliation so a lost admin token can be replaced through Vercel env without printing secrets in logs

  • Added /api/v1/auth/token for logged-in admins to set a custom token from settings

  • Added /settings with token confirmation and local storage update after successful rotation

  • Updated build/runtime diagnostics to show whether PCP_ADMIN_TOKEN is configured without revealing its value

  • Added setup/init repair for initialized databases missing the ui_auth credential row

• 2026-06-23 - Added Docker Compose deployment path

  • Added versioned Dockerfile and docker-compose.yml with image tag default personal-context-protocol:0.1.2

  • Added root VERSION consistency checks for package, Dockerfile, Compose, and runtime fallback

  • Updated deployment docs for admin token reset through PCP_ADMIN_TOKEN

• 2026-06-23 - Added zero-config first-login admin token flow

  • Generated and logged first-login admin tokens only when PCP_ADMIN_TOKEN is absent

  • Added credential-state-specific setup/login errors and deployment guide links

  • Updated deployment, security, and protocol docs for the generated-token exception

• 2026-06-23 - Bumped app version and added Bark notification helper

  • Bumped release metadata to 0.1.1 for the current change round

  • Added npm run notify:bark with app name/version prefixes and passive Bark delivery

  • Added a Bark env example and checklist rules for version bumps and notification secrecy

• 2026-06-25 - Trash model, drag-to-move, events toggle, scroll fixes (v0.1.14)

  • Replaced archive with trashcan: NavSidebar shows a Trash section with archived items, restore/delete-permanently context menu, and “Empty trash” for bulk permanent deletion. New DELETE endpoints for sessions and topics. Topic archive POST now accepts {archived:false} to restore.

  • Drag-to-move sessions: drag a session item onto a topic group; the topic auto-expands on hover and the session moves.

  • Events sidebar auto-hides: a toggle button on the right edge (ChevronLeft/Right) shows/hides events. Defaults to hidden.

  • Fixed workspace height: double h-[calc(100vh-57px)] removed (workspace now h-full inside the dashboard grid). Scroll-to-bottom button threshold lowered to 3 messages.

  • Topic dropdown in session edit now filters out archived topics.

  • Added docs/versions/ directory with per-release notes (v0.1.12–v0.1.14).

  • Bark notification sent on dev completion. 94 tests pass.

• 2026-06-25 - Session URL routing, scroll-to-bottom, overflow fix (v0.1.14)

  • Dashboard now uses URL-driven session selection: clicking a session pushes /dashboard?session=, making every session shareable while the sidebar stays visible. Removed the standalone /sessions/[id] page (redirects); removed “Open page” button.

  • Fixed y-overflow scroll: the main container uses h-[calc(100vh-57px)] overflow-hidden with flex-1 overflow-y-auto on the message column. Long single messages no longer break the viewport.

  • Added scroll-to-bottom button (ArrowDown) that appears when the user scrolls up past ~8 messages; auto-scrolls to latest on session load.

  • 93 tests pass; build clean.

• 2026-06-25 - Agent read-messages endpoint + full-history instruction (v0.1.13)

  • Fixed root cause of agents failing to record context: protocol pointed review at admin endpoint (UI-token only), so agents couldn’t read past messages. Instruction didn’t tell agents to record ALL messages either.

  • Added GET /api/v1/agent/sessions/:id/review (access-token scoped) so an agent reads its own session history and picks up from the correct ordinal

  • Protocol descriptor now has read_messages route + existing_message_count + hint; instruction says “Record ALL messages — every user and assistant response, the full history”

  • 93 tests pass; verified: agent review returns scoped history, recording picks up from correct ordinal

• 2026-06-24 - Chat-bubble alignment + scroll (v0.1.12)

  • Rewrote MessageList with chat-bubble layout: user messages float right (sky-600 rounded-2xl), agent/assistant/system/tool/correction float left (white/grey rounded-2xl); compaction/system blocks span full width. Message bubbles capped at 75-85% width for readability. Role badge, ordinal, and pencil-edit inline in the bubble header.

  • Messages column now scrolls independently (flex-1 overflow-y-auto) with the ImportPanel pinned below; the outer flex container uses h-[calc(100vh-57px)] overflow-hidden to constrain it. Session detail page made a flex-col min-h-screen with the grid flex-1 + overflow-hidden for independent scroll.

  • Version 0.1.12; 92 tests pass.

• 2026-06-24 - Compaction rendering, mixed ingest, and v0.1 hardening (v0.1.11)

  • Patch-bumped to 0.1.11

  • Compactions are now first-class readable content: GET /api/v1/sessions/:id/compactions + a CompactionList rendered system-prompt-style (labeled Summary/Timeline/Decisions/Requirements/Open questions/Artifacts/Warnings) in the workspace and session page; when a session has compactions but no messages the messages pane says “No raw messages recorded. This session has compact summaries.”

  • Ingest supports messages + compaction together: new mixed kind + <PCP_INGEST> tag; agent ingest and human import both record messages and a compaction. Import response is now { ok, imported: { messages, compactions }, skipped, notice }

  • Hardening — startup validation: shared validateRuntimeConfig (missing + malformed: DATABASE_URL scheme, secret length, non-absolute PCP_APP_URL like ${VERCEL_URL}); surfaced secret-free in setup/status and the home setup card

  • Hardening — API docs sync: a drift test asserts every route under src/app/api/v1 is documented in protocol.md (params normalized)

  • Tests: config validator (7), ingest mixed/compact (4 new), API-doc drift (per-route). 92 tests pass

  • Verified live: compact-only import stores a compaction (0 messages, correct notice) and renders; mixed PCP_INGEST records 2 messages + 1 compaction; setup/status returns config_issues

• 2026-06-24 - Admin message edit/delete with multi-select (v0.1.10)

  • Patch-bumped to 0.1.10

  • Added admin (UI-token) message correction: PATCH /api/v1/sessions/:id/messages/:messageId (edit) and POST /api/v1/sessions/:id/messages/delete (bulk delete, ownership-checked); audited message.edited / message.deleted. AI tokens remain strictly append-only; documented the human-admin exception in data-model and docs/AGENTS.md

  • New shared MessageList component (replaces the two inline renderers): inline edit, multi-select with select-all + shift-click range select, bulk delete, and auto-fold long messages to 5 lines (line-clamp-5) while selecting

  • Verified live: edit fixes a wrong import; bulk delete removes selected (ordinals keep gaps); cross-session ids rejected (deleted=0); edit without UI token → 401; agent append continues from max(ordinal)+1 after deletes. 53 tests pass

• 2026-06-24 - Session recording modes + token rename (v0.1.9)

  • Patch-bumped to 0.1.9

  • Added sessions.mode (wild default / exact, migration 007). The mode is surfaced to the agent in the protocol descriptor (recording_mode + recording_guidance) and the generated instruction: wild = may redact unsafe secrets, exact = verbatim incl. credentials for task migration. Workspace has a Wild/Exact toggle

  • Token rename: PATCH /api/v1/sessions/:id/tokens { token_id, name } (also { token_id, revoke: true }); names auto-suffixed distinct on create and rename; rename button in the token modal

  • Verified live: protocol/instruction reflect the mode; rename updates the name distinctly; new tokens get distinct names; revoke still rejects. 53 tests pass

• 2026-06-24 - Human fallback paste-import with auto-merge (v0.1.8)

  • Patch-bumped to 0.1.8

  • Added POST /api/v1/sessions/:id/import (UI token): parses a pasted agent fallback block (forgiving formats incl. agent wrapper JSON) and records it, skipping messages already present (dedup by role + content) so re-pasting merges cleanly; <PCP_COMPACT> stored as a compaction

  • New pure import-merge.ts (dedupeNewMessages) + tests; parseIngestPayload gained a maxMessages option for larger human imports

  • Added an ImportPanel (terminal-style paste box) below the messages widget on the session detail page and the dashboard workspace

  • Verified live: agent-wrapper JSON imports; re-paste imports nothing new; superset imports only the delta; compact block stored; empty/garbage returns 422; ordinals stay monotonic. 51 tests pass

• 2026-06-24 - Public sessions, token revocation, recording-URL origin fix, front-page polish (v0.1.7)

  • Patch-bumped release metadata to 0.1.7

  • Added sessions.public (migration 006); GET /api/v1/public/sessions/:id and /s/:id render a read-only view without the admin token; private sessions return 404 to avoid leaking existence

  • Token revocation: PATCH /api/v1/sessions/:id/tokens { token_id } sets revoked + audit event; dashboard token-management modal lists tokens with one-click revoke; workspace gained a public/private toggle + copyable public link

  • Recording URL: hardened resolveAppBaseUrl to ignore a non-absolute PCP_APP_URL (e.g. the literal ${VERCEL_URL}) and fall back to request origin; the browser now builds the recording URL + instruction from window.location.origin so it always matches where the UI is open

  • Front page: staggered fade-in-up load animations (with prefers-reduced-motion guard); footer shows the deployed vX.Y.Z

  • Added resolveAppBaseUrl tests; 46 tests pass

  • Verified live: public read returns messages only when public (404 when private), token revoke rejects the agent immediately

• 2026-06-24 - Fixed admin token not rotating on deploy (v0.1.6)

  • Root cause: migration 003 backfilled pre-existing credentials as source = 'user', which preserved them forever, so a new deploy printed “user-set admin credential preserved” and generated no token

  • Added one-time, self-guarded migration 005 (0004_default_token_rotates.sql) that resets mis-marked user rows to deploy; mirrored in deploy-init and ensureDatabaseSchema. After it runs, the deploy generates and prints a fresh token

  • Default for any credential not set in Settings is now deploy (rotates each deploy); only a Settings-set token (tagged user after migration 005) or PCP_ADMIN_TOKEN (env) stops rotation

  • Clarified the deploy-init “preserved” log so the user is notified that a Settings-set token is in effect and how to resume rotation

  • Verified live: a row mis-marked user rotates and prints a new token after the corrective migration; a Settings-set token (tagged after 005) is preserved across deploys

• 2026-06-24 - ChatGPT-style nav, context menu, and uncategorized sessions (v0.1.5)

  • Patch-bumped release metadata to 0.1.5

  • Made sessions.topic_id and messages.topic_id nullable + idempotent migration 0003_optional_topic.sql (mirrored in setup-schema and deploy-init)

  • Added GET/POST /api/v1/sessions (list all + create with optional topic); PATCH /sessions/:id accepts topic_id: null to move to Uncategorized

  • Null-safe session-title uniqueness within the topic group or the uncategorized group (new session-store.ts; recording-store rename made null-safe)

  • Replaced the two-column topic/session sidebars with one ChatGPT-style nav: collapsible topic groups + Uncategorized group, sessions nested as items; removed topic-sidebar.tsx and session-sidebar.tsx

  • Right-click + long-press context menu to remove (archive) topics/sessions, with confirm; removing a topic moves its sessions to Uncategorized so none are lost

  • Verified end-to-end against live Postgres: nullable columns, uncategorized create + auto-suffix, grouping, agent append to a no-topic session (message.topic_id NULL), move to/from a topic, archive

• 2026-06-23 - Per-deploy admin token rotation + recovery guidance (v0.1.4)

  • Patch-bumped release metadata to 0.1.4

  • Added ui_auth.source (deploy/env/user) + idempotent migration 0002_admin_token_source.sql; pre-existing credentials migrate to user so an upgrade never rotates a token already in use

  • deploy-init now rotates the admin token on every deploy unless PCP_ADMIN_TOKEN (env) or a Settings-set (user) token owns the credential; the fresh token is printed once

  • Settings rotation tags user; setup/init and env reconcile tag their source

  • Login wrong-password error now explains deploy-log lookup, PCP_ADMIN_TOKEN reset, and their precedence, with a link to the deployment guide’s admin-token-recovery section

  • Dashboard shows a Tailwind warning banner below the nav when a deploy-generated token is in use; auth/check returns ui_token_source

  • Verified end-to-end against live Postgres: first deploy generates token; redeploy rotates it (old token rejected); env-set and user-set tokens preserved; wrong token returns recovery link

• 2026-06-23 - Added agent recording-URL model (v0.1.3)

  • Patch-bumped release metadata to 0.1.3 (VERSION, package.json, package-lock, version.ts, Dockerfile, docker-compose, pyproject)

  • Version policy: stays in the v0.1 line. A 0.2.0 bump is gated on completing v0.1 Remaining Hardening (startup validation, setup integration tests, security audit, API docs sync); it is not triggered by shipping a feature while that work is open. Corrected an earlier 0.2.0 bump back to 0.1.3 for this reason.

  • Added pure helper libs: naming, recording-url, agent-protocol, ingest, agent-errors, token-expiration

  • Added compactions table + idempotent migration 0001_agent_recording.sql and setup-schema bootstrap

  • Added public discovery routes (/r/:id, /agent/resolve, /agent/sessions/:id/protocol) and agent write routes (messages, compact, ingest) with structured { ok, code, retryable, message, next_steps } errors

  • Token expiration choices (1h/24h/7d/30d/never, default 7d; NULL = never); token list shows active/expired/revoked + last used

  • One-click topic/session creation with generated default names; duplicate titles auto-suffixed; AI-suggested titles normalized + de-duped within topic

  • Session detail UI shows recording URL, expiration controls, copyable URL+token agent instruction, and issued-token status

  • Added tests (naming, recording-url, protocol, ingest, token-expiration, agent-errors); 43 tests pass

  • DB-backed routes verified via typecheck + build; no live Neon DB in the test env, so route-level append/compact/expiry rejection are covered by their pure building blocks plus example curl in docs/agent-instructions.md

• 2026-06-23 - Added deploy-time database/admin bootstrap

  • Bumped release metadata to 0.1.2 for the current change round

  • Added build/start deploy initialization for schema, app instance, and admin credential

  • Added Docker .env generation and npm run docker:up

  • Updated login to offer fallback initialization only when deploy initialization did not run