# 5chan Full LLM Context

> 5chan is a static, serverless, adminless, decentralized imageboard client built on the Bitsocial protocol.

This file is generated by `scripts/generate-llms-files.mjs`. Do not hand-edit it; update the source docs or generator config, then run `yarn llms:generate`.

Use this as compiled context only. Source files, tests, manifests, and live/runtime evidence remain authoritative.

## Index

- [README.md](#readmemd)
- [AGENTS.md](#agentsmd)
- [PRODUCT.md](#productmd)
- [DESIGN.md](#designmd)
- [src/AGENTS.md](#srcagentsmd)
- [scripts/AGENTS.md](#scriptsagentsmd)
- [docs/agent-playbooks/known-surprises.md](#docsagent-playbooksknown-surprisesmd)
- [docs/agent-playbooks/long-running-agent-workflow.md](#docsagent-playbookslong-running-agent-workflowmd)
- [docs/agent-playbooks/bug-investigation.md](#docsagent-playbooksbug-investigationmd)
- [docs/agent-playbooks/translations.md](#docsagent-playbookstranslationsmd)
- [docs/agent-playbooks/skills-and-tools.md](#docsagent-playbooksskills-and-toolsmd)
- [docs/agent-playbooks/verification.md](#docsagent-playbooksverificationmd)
- [docs/agent-playbooks/hooks-setup.md](#docsagent-playbookshooks-setupmd)
- [docs/upload-automation-retest-checklist.md](#docsupload-automation-retest-checklistmd)

---

## README.md

Source: https://github.com/bitsocialnet/5chan/blob/master/README.md

```markdown
[![Build Status](https://img.shields.io/github/actions/workflow/status/bitsocialnet/5chan/ci.yml?branch=master)](https://github.com/bitsocialnet/5chan/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/endpoint?url=https://bitsocialnet.github.io/5chan/badges/coverage.json)](https://github.com/bitsocialnet/5chan/blob/master/scripts/write-coverage-badge.mjs)
[![Release](https://img.shields.io/github/v/release/bitsocialnet/5chan)](https://github.com/bitsocialnet/5chan/releases/latest)
[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-red.svg)](https://github.com/bitsocialnet/5chan/blob/master/LICENSE)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bitsocialnet/5chan)

<img src="https://github.com/plebeius-eth/assets/blob/main/5chan-logo.jpg" width="378" height="123">

_Telegram group for this repo https://t.me/fivechandev_

# 5chan

5chan is a serverless, adminless, decentralized and open-source imageboard built on the [Bitsocial protocol](https://bitsocial.net). It features the classic imageboard directory structure, but with a crucial difference: **anyone can create and own boards, and multiple boards can compete for each directory slot**.

## Key Features

### Decentralized Board Ownership
Unlike traditional imageboards, 5chan has no global admins or central authority. Anyone can create unlimited boards using [5chan Board Manager](https://github.com/bitsocialnet/5chan-board-manager). Each board owner runs their own P2P node that users connect to peer-to-peer, giving them complete control over their board's content, moderation, and rules.

### Competitive Directory System
5chan maintains the familiar imageboard directory structure (Japanese Culture, Video Games, Interests, Creative, etc.), but introduces competition: **multiple boards can compete for each directory slot**. For example, there can be unlimited "Business & Finance" boards, but only the highest-voted one appears in the directory on the homepage.

Currently, directory assignments are temporarily handpicked by developers through GitHub pull requests. In the future, each directory will have its own voting page. 5chan Pass holders are expected to participate in directory voting, while final governance mechanics are still being designed to include BSO-holder alignment instead of pass-only final control.

### How It Works

- **Current System**: Developers manually curate directory assignments by reviewing pull requests to the [5chan directory files](https://github.com/bitsocialnet/lists/tree/master/5chan-directories).

- **Future System**: Each directory will have its own voting page listing the boards competing for that slot. 5chan Pass holders are expected to participate in directory voting, while final governance mechanics are still being designed to include BSO-holder alignment instead of pass-only final control.

- **Accessing Boards**: Users can access any board at any time using its address, regardless of directory assignment. Boards can be accessed via the search bar, by subscribing to them (which adds them to the top bar), or by directly navigating to their address.

### Future Roadmap

#### In-App Board Creation

Creating boards directly from the 5chan web app (5chan.app) is planned. This requires connecting via RPC to a bitsocial node—technically already possible, but there's no default connection configured. A default connection would require a public RPC service (similar to what Infura provides for crypto wallets, but for bitsocial nodes). This would allow all users to be connected to a P2P node by default using a free tier subscription in the background, potentially monetized via ads injected in the RPC service-owned boards.

#### Directory Voting

Directory voting pages are planned for each slot on 5chan. These pages will list the competing boards for that directory, and 5chan Pass holders are expected to participate in voting. Final governance mechanics are still being designed to include BSO-holder alignment instead of pass-only final control.

## Downloads

- **Web version**: https://5chan.app (also available using Brave/IPFS Companion on https://5chan.eth)
- **Desktop version** (full P2P bitsocial node, seeds automatically): Available for Mac/Windows/Linux, [download from the release page](https://github.com/bitsocialnet/5chan/releases/latest)
- **Mobile version**: Available for Android, [download from the release page](https://github.com/bitsocialnet/5chan/releases/latest)

## Run 5chan in Your Browser With a Local Node

If you want the full P2P node but prefer opening 5chan in your normal browser instead of using the desktop app, use [bitsocial-cli](https://github.com/bitsocialnet/bitsocial-cli). It runs the Bitsocial/IPFS node and serves the bundled 5chan Web UI locally, so you do not need to run this repository separately.

```sh-session
npm install -g @bitsocial/bitsocial-cli
bitsocial daemon
```

When the daemon starts, it prints a `WebUI (5chan - Imageboard-style UI)` URL. Open that URL in your browser to use 5chan through your local node. See the [bitsocial-cli daemon docs](https://github.com/bitsocialnet/bitsocial-cli#running-daemon) for details.

## Creating a Board

In the bitsocial protocol, a 5chan board is called a _community_. To deliver the expected 5chan imageboard UX, a board should run on a bitsocial node together with [5chan Board Manager](https://github.com/bitsocialnet/5chan-board-manager). The board manager applies imageboard-style lifecycle rules that bitsocial communities do not enforce by themselves: thread limits, bump limits, archived-thread retention, and purging of author-deleted content.

To create and run a board:

1. Follow the Docker Compose flow in the [5chan-board-manager README](https://github.com/bitsocialnet/5chan-board-manager#docker-compose-recommended);
2. Create your community and add it to 5chan Board Manager using the commands shown there;
3. Keep the manager running so it can apply 5chan board behavior such as thread archiving, bump limits, and retention cleanup.

Once created, anyone can connect to your community using any bitsocial client (such as 5chan) by using the community address. The address is not stored in any central database—bitsocial is a pure peer-to-peer protocol.

Without 5chan Board Manager, a community can still be opened in 5chan, but it will not behave like a conventional imageboard board: old threads will not be archived when they fall past the last page, bump limits will not be enforced, archived threads will not be purged after the retention window, and author-deleted content will not be automatically purged.

**Note**: Creating boards directly from the 5chan web app is planned for the future (see [Future Roadmap](#future-roadmap)).

## Submitting Your Board to a Directory

To have your board appear in a directory on the 5chan homepage:

1. Ensure your board meets these requirements:
   - Active and well-moderated
   - Relevant to the directory category
   - **99% uptime** (since a board acts like its own server—it's a P2P node)

2. Open a pull request on GitHub by editing the relevant file in the [5chan-directories folder](https://github.com/bitsocialnet/lists/tree/master/5chan-directories)

3. Add your board's entry with:
   - Title: in the format `/directoryCode/ - Title`, e.g. "/biz/ - Business & Finance";
   - Address: the bitsocial community address, whether IPNS key (`12KooW...`) or readable crypto address (`mydomain.eth`);
   - NSFW status: `true` or `false`, must match the standard classification for the directory code.

4. The developers will review your PR and merge it if approved

**Note**: Even if your board isn't assigned to a directory, users can still access it at any time using its bitsocial community address. Directory assignment only affects visibility on the homepage.

## Development

### Prerequisites

- Node.js 22.12.0, pinned in [`.nvmrc`](./.nvmrc)
- Corepack enabled once per machine: `corepack enable`

### Contributor Setup

1. Run `nvm install && nvm use`
2. Run `corepack enable` once
3. Use plain `yarn install`, `yarn build`, and `yarn test`

### Setup

1. Clone the repository
2. Install dependencies: `yarn install`
3. Start the web client: `yarn start`

The dev server normally runs at https://5chan.localhost via [Portless](https://github.com/vercel-labs/portless), which gives each Bitsocial project a stable, named URL instead of a random port. Portless 0.11 serves this URL through an HTTPS proxy on port 443, so the first `yarn start` after install or proxy reset may prompt for sudo; accept the prompt so the URL can stay portless. On non-`master` branches, or when another legacy process is already holding the canonical route, `yarn start` will automatically use a branch-scoped `*.5chan.localhost` URL instead of failing. To bypass Portless and use a plain Vite dev server, run `PORTLESS=0 yarn start`; it will start at `http://localhost:3000` and automatically fall forward to the next free port if `3000` is already in use.

For device testing on a USB-connected Android phone (without relying on `5chan.localhost` DNS from the device):

- `yarn start:android-usb` starts Vite bound to `127.0.0.1` and runs `adb reverse`, so the phone can load the dev site at `http://localhost:3000`. When the server is up, it opens that URL in each connected device’s default browser via `adb`. Set `ANDROID_USB_OPEN_BROWSER=0` to skip auto-open. Requires [Android platform-tools](https://developer.android.com/tools/releases/platform-tools) (`adb` on your `PATH`), USB debugging enabled, and the device showing as `device` in `adb devices`.

### Scripts

- **Web client**: `yarn start` (https://5chan.localhost)
- **Web client (Android phone over USB)**: `yarn start:android-usb` (see above)
- **Electron client** (must start web client first): `yarn electron`
- **Electron client** (don't delete data): `yarn electron:no-delete-data`
- **Web client and electron client**: `yarn electron:start`
- **Web client and electron client** (don't delete data): `yarn electron:start:no-delete-data`

### Challenge Types

Bitsocial communities can require users to solve one or more anti-spam challenges before a publication is accepted. 5chan already supports multiple challenge types, including `url/iframe` challenges so [Mintpass](https://github.com/bitsocialnet/mintpass) communities can run their iframe flow directly inside a modal. The modal first shows a hostname confirmation (showing only the host for mintpass.org, full URL otherwise), then opens the HTTPS iframe with the current theme, replaces `{userAddress}` tokens with the signed-in address, and submits automatically when the user finishes.

5chan also has an optional UX integration with [`@bitsocial/ai-moderation-challenge`](https://github.com/bitsocialnet/ai-moderation-challenge): when a failed verification contains the exact message `This media was already posted recently.`, 5chan abandons the rejected pending publication, returns to the originating post form, preserves the draft, and shows the message inline. This string is an intentionally small cross-package contract rather than a package dependency. Challenges that omit it, or return any other error, continue through the normal generic challenge-error flow.

While waiting for a challenge or answer verification, unpublished posts explain that the board is checking the post or verifying its challenge answers. The AI moderation notice appears only after challenge answers have been submitted, while waiting for verification, so it does not appear before Spamblocker opens. It also requires the target board's cached public `community.challenges` to contain the package's exact description, `Moderate Bitsocial publications with AI.`, with type `text/plain`. Unknown or customized metadata gets no AI notice. This describes the board's configuration, not live AI progress or confirmation that its earlier checks passed; other publishing states and errors retain their existing messages.

### Build

The Linux/Windows/macOS/Android build scripts are in [.github/workflows/release.yml](https://github.com/bitsocialnet/5chan/blob/master/.github/workflows/release.yml)

## License

5chan is open-source software (GPL-3.0-or-later) with no owner—anyone can host their own instance on any domain. The operator of any domain is merely hosting the web app and does not own, create, moderate, or control 5chan or any board content, which is stored peer-to-peer and generated by board owners and users.
```

---

## AGENTS.md

Source: https://github.com/bitsocialnet/5chan/blob/master/AGENTS.md

```markdown
# AGENTS.md

## Purpose and priority

These are the shared instructions for agents working on 5chan. Explicit user instructions take precedence over repository workflow guidance. MUST rules are mandatory; SHOULD rules are defaults. Read linked playbooks only when the task needs them.

Use judgment for routine implementation choices and continue authorized work. Ask only when missing information materially changes the outcome or an action needs authorization that has not already been given. Do not turn a skill's suggested procedure into an extra approval gate.

## Product and source of truth

5chan is a static, serverless, adminless, decentralized imageboard client built on the Bitsocial protocol. Board content comes from peers, not the app origin. Preserve hash routing and static deployment unless the user requests an architectural change.

Code, tests, manifests, source docs, and runtime evidence establish behavior. This file, skills, playbooks, task logs, and generated `llms*.txt` are orientation and policy; verify their technical claims against source before editing. Check the installed dependency version before assuming a nearby repository supplies its code.

For an unexpected repo-specific issue, tell the contributor and continue independent work. After confirmation, record only recurring issues with a concrete mitigation in [known-surprises.md](docs/agent-playbooks/known-surprises.md).

## Working principles

- Define completion for non-trivial work. Continue through implementation, relevant verification, and fixes until the requested outcome is complete; stop at the user’s requested boundary.
- Understand the flow before editing. Prefer skipping unnecessary work, reusing repository code, standard-library/native features, then installed dependencies, before writing new code.
- Keep diffs scoped. Preserve unrelated edits; do not reformat, rename, or refactor adjacent code without a task-related reason.
- Simplicity must preserve correctness, clarity, accessibility, validation, security, and useful tests.
- For a bug tied to a file or line, inspect `git log`/`git blame`, then relevant `git show`, before fixing it. See [bug-investigation.md](docs/agent-playbooks/bug-investigation.md).
- Use existing evidence or a focused test before adding instrumentation. Add runtime logging when it resolves uncertainty; remove task-owned instrumentation after verification.

## Task router

| Task | Required guidance/check |
|---|---|
| Visual design, layout, CSS, or themes | Read the relevant guidance in [DESIGN.md](DESIGN.md); review against its Do/Don't list |
| Files under `src/` or `scripts/` | Read the directory's `AGENTS.md` |
| Code or automation changed | Select affected checks using [verification.md](docs/agent-playbooks/verification.md); use `agent:verify` for integration/build changes or an explicitly requested full pass |
| React state, effects, data flow, or rendering performance changed | Review relevant React guidance; run `yarn doctor:check` and affected `yarn perf:check` scenarios |
| UI behavior/layout changed | Verify the affected flow; select browsers/viewports using [verification.md](docs/agent-playbooks/verification.md) |
| Loading/navigation/performance work | Add a throttled Chromium pass; see [low-spec-verification.md](docs/agent-playbooks/low-spec-verification.md) |
| Translation keys/values | Use the `translate` skill; one process applies locale changes at a time |
| `package.json` changed | Run `corepack yarn install` to synchronize `yarn.lock` |
| Dependencies, moved files, or imports changed | `yarn boundaries` (part of `yarn lint`) must pass; see module boundaries in [src/AGENTS.md](src/AGENTS.md). Run advisory `yarn knip`; resolve relevant new findings |
| AI workflow files changed | Edit shared sources, run `yarn ai-workflow:sync`, then `yarn ai-workflow:check` and `yarn ai-workflow:test` |
| Public English docs or AI context changed | Run `yarn llms:generate` and include resulting `public/llms*.txt` changes |
| Version or changelog changed | Run `yarn blotter:check`; follow the `release` skill's user-facing wording rules |
| Open PR feedback or merge readiness | Use `review-and-merge-pr` within the user's requested scope |
| Work needs a durable handoff/resumption | Use [long-running-agent-workflow.md](docs/agent-playbooks/long-running-agent-workflow.md) |

## Code and design

- Use Corepack-managed Yarn 4, never npm for project dependency changes. Pin exact versions and keep the lockfile synchronized.
- Stack: React 19, TypeScript, Zustand, React Router v6, Vite, `@bitsocial/bitsocial-react-hooks`, i18next, oxlint, oxfmt.
- Keep page composition in `src/views/`, reusable UI in `src/components/`, hooks in `src/hooks/`, shared state in `src/stores/`, helpers in `src/lib/`, static data in `src/data/`. Dependencies flow one way between those layers; see module boundaries in [src/AGENTS.md](src/AGENTS.md).
- Use Zustand for shared/global state; local component state may use `useState`.
- Use Bitsocial hooks for protocol data access. Do not fetch data in effects or synchronize derived state with effects; derive values during render.
- Reuse hooks for repeated logic. Model complex flows clearly instead of accumulating boolean flags.
- Use React Router for navigation, not manual history manipulation.
- Add comments for non-obvious constraints or logic, not for obvious code.
- Preserve the classic imageboard appearance: square edges, 1px theme borders, flat surfaces, compact text, and the theme palette.
- No rounded corners, decorative pills/badges, row/card hover background fills, CSS transitions/animations, soft shadows, glass, gradients, or new marketing colors on product UI.
- Small flat per-entity color indicators are allowed when functional. Technical surfaces follow the same compact, theme-aware design.

## Git and ownership

- Keep `master` releasable. Start new changes on short-lived `codex/feature/*`, `codex/fix/*`, `codex/docs/*`, or `codex/chore/*` branches unless the user requests otherwise.
- For an unrelated task while another branch is active, create a separate descriptive worktree from `master`. Prefer `./scripts/create-task-worktree.sh <type> <descriptive-slug>`; it installs dependencies.
- Related delegated slices may share the task worktree with non-overlapping file ownership. Never switch branches underneath another agent.
- Stage only task-owned changes, using a selective index patch when files contain mixed edits. Do not use `git add -A` as a default.
- Never commit secrets or generated build output. Preserve preexisting artifacts and unrelated changes during cleanup.
- Only commit, push, publish, or merge when authorized. Permission already given for the action persists through its necessary steps.
- When opening a requested PR, target `master` and make it ready for review so review bots run.
- After an authorized merge, clean up only the verified merged branch/worktree; preserve any later or unrelated work. Do not run Git cleanup from lifecycle hooks.
- Use `gh` for GitHub operations. Commit/issue formatting lives in [commit-issue-format.md](docs/agent-playbooks/commit-issue-format.md); provide suggestions when requested, not on every answer.

## Verification and resource ownership

- Verify the affected behavior with the narrowest reliable checks. Add regression tests for non-trivial, testable bugs; do not add tests that merely restate a reversible wording or formatting edit.
- Run applicable checks for the final change once. Repeat or broaden them only after relevant edits, failures, or unresolved concerns. Preserve explicit user, CI, and release requirements. Documentation-only changes need document/workflow checks.
- Before heavy work, inspect existing processes. Stop only stale processes owned by this task; never stop a process of unclear ownership.
- Serialize installs, builds, full tests/coverage, React Doctor, Android/Electron work, and browser profiling across the task. One agent owns heavy verification.
- Use `corepack yarn exec vitest run --maxWorkers=2 [paths]` for agent-run tests. Do not use watch mode or the package's default four-worker setting.
- React Doctor is guidance for newly introduced issues, not a score target. Knip and coverage are advisory; do not invent new repository-wide gates.
- Default to fresh isolated Playwright sessions. Reuse a contributor's current browser only when explicitly authorized; do not ask again after session mode is established.
- Use `./scripts/pw-session.sh open <session> ...` and `close <session>` for every browser session. One browser may be active machine-wide. Exit 75 means busy; defer or use the wrapper's bounded wait.
- Run browser engines sequentially. Reuse each session for desktop/mobile and close the exact session in cleanup even after failure. Never use `close-all` or `kill-all`.
- Reuse a compatible dev server in the same worktree when safe. Otherwise record and clean up the server/process you start. Never start a server for a documentation-only task.
- Review the final task-owned diff. Use `code-quality-review` for non-trivial changes or an explicit review request; apply high-confidence findings within existing authorization.
- After a bug fix or substantive review correction exposes a preventable mistake, use [retro](.agents/skills/retro/SKILL.md) before finishing to consider the smallest useful prevention. Existing coverage or no additional check can be the right outcome.

## Skills and delegation

- Shared skills live in `.agents/skills/`; shared roles in `.agents/roles/`. `.claude/skills/` and harness agent files are generated compatibility outputs. See [skills-and-tools.md](docs/agent-playbooks/skills-and-tools.md).
- Keep harness-specific hooks, permissions, and metadata explicit; byte-identical files do not establish equivalent runtime behavior.
- Keep model and reasoning choices out of committed skills and custom agents. Use the app’s runtime defaults, parent inheritance, and supported invocation-time choices; do not invent a `latest` alias or require model research for ordinary tasks.
- Delegate substantial independent work when it improves speed, context isolation, or independent review. Small or tightly coupled tasks can stay with the parent.
- Give each child its scope, acceptance criteria, context, file ownership, and evidence to return. For an independent review, omit the parent's verdict.
- Parallelize read-heavy work and non-overlapping edits; use at most four active workers by default. Children do not each run full builds. Browser work always remains serialized.
- Use built-in worker/explorer roles where available; custom roles cover browser checks, profiling, Android, translation, and review. Avoid a compulsory chain of specialist agents.
- Use relevant React skill guidance for state/effect/data-flow or performance work. Load only rules that fit this Vite client; use `you-might-not-need-an-effect` for a focused effect review when the reason is unclear.
- Prefer existing tools and local CLIs. Use external documentation when versions matter. Do not search for or install additional skills merely because a normal coding task mentions their domain.
- Keep tool catalogs relevant. Deferred MCP loading can reduce context overhead, but unnecessary integrations still add choices; disable unused tools when their overhead is observable. Playwright CLI remains the project browser verification path.

## React diagnostics and runtime performance

`yarn agent:verify` and CI run `yarn doctor:check` for task-diff source diagnostics and `yarn perf:check` for deterministic runtime scenarios. Doctor remains advisory for relevant new findings; a score is not a target. Run affected scenarios after React state/effect/subscription/rendering changes, and `yarn perf:test` after React, Bippy, or collector upgrades. Install the pinned browser once with `yarn perf:install`; ordinary edit hooks still only format files.

Development builds initialize the bounded Bippy collector before React and expose `window.__REACT_PERF__.reset()` / `.snapshot()`. It counts committed component updates by instance; it does not identify wasted work or count aborted renders. A root React Profiler supplies measured render duration. Missing instrumentation, dropped events, and exceeded scenario budgets fail the runtime check. Use `yarn perf:record --scenario <name>` for JSON and native Chrome traces; use `profile-browsing` for the evidence contract and broader investigations.

`yarn build:profile` creates a separate `build-profile/` output with `react-dom/profiling` and sourcemaps; `yarn preview:profile` serves it. Ordinary production excludes the collector and Profiler boundary. A normal production preview can measure page timing but cannot provide these React timing/count checks.

Development builds retain Agentation and `window.__ELEMENT_SOURCE__` for visual feedback/source inspection. The runner suppresses Agentation during capture. Run browser tools and heavy checks serially; the performance runner owns its browser/server lifecycle and uses the shared browser resource lock. Stop or wait for an existing browser owner before starting another capture.

## Local commands and playbooks

Canonical dev URL: `https://5chan.localhost`; other worktrees may use branch-scoped `*.5chan.localhost`. Preserve the launcher's HTTPS proxy on port 443. Direct Vite fallback: `PORTLESS=0 yarn start`. USB Android: `yarn start:android-usb` (`ANDROID_USB_OPEN_BROWSER=0` skips opening the phone browser).

Common checks: `yarn agent:verify`, `yarn doctor`, `yarn knip`, `yarn ai-workflow:sync`, `yarn ai-workflow:check`, `yarn ai-workflow:test`, `yarn llms:generate`, `./scripts/pw-session.sh status`.

Load details on demand: [hooks](docs/agent-playbooks/hooks-setup.md), [verification](docs/agent-playbooks/verification.md), [translations](docs/agent-playbooks/translations.md), [skills/tools](docs/agent-playbooks/skills-and-tools.md), [long-running work](docs/agent-playbooks/long-running-agent-workflow.md), [known surprises](docs/agent-playbooks/known-surprises.md).
```

---

## PRODUCT.md

Source: https://github.com/bitsocialnet/5chan/blob/master/PRODUCT.md

```markdown
# Product

## Register

product

## Users

5chan is for people who already understand classic imageboards, especially users whose habits depend on dense boards, terse navigation, reply flows, catalog scanning, familiar colors, and old-school post mechanics. The primary user should be able to land on 5chan and feel that the interface behaves like an imageboard they already know.

Secondary users include board owners, board moderators, and contributors building decentralized features around Bitsocial. Their tools should still feel native to the same imageboard environment instead of becoming a separate admin dashboard aesthetic.

## Product Purpose

5chan exists to preserve the classic imageboard habit while removing the dependency on global admins. It keeps the familiar imageboard directory structure and browsing experience, but runs on the Bitsocial protocol so anyone can create, own, and moderate boards independently.

Success means experienced imageboard users do not need to relearn how to browse, post, reply, search, use catalogs, read threads, or understand board identity. The decentralization should matter structurally, but it should not make the core user experience feel unfamiliar.

## Brand Personality

5chan should feel familiar, blunt, resilient, and low-friction. It is not polished in the startup sense. It should feel like a functional old internet place that kept its original interface discipline while replacing the governance layer underneath.

The voice is plain and direct. Prefer short labels, conventional imageboard wording, and visible system behavior over explanatory product copy.

## Anti-references

Do not make 5chan look like a modern social network, crypto app, SaaS dashboard, mobile-first content platform, or polished community product. Avoid feed algorithms, engagement framing, large hero layouts, decorative cards, rounded modern controls, soft gradients, animated brand flourishes, and "Web3" visual language.

Do not modernize classic imageboard affordances unless there is a concrete usability, accessibility, or protocol-driven reason. When 5chan needs custom decentralized features, they should look like they belong inside the existing classic imageboard UI.

Do not imply official affiliation with any existing imageboard. The design goal is alignment with long-standing imageboard user expectations, not brand ownership or endorsement.

## Text and Expression

5chan adds no emoji affordances: no emoji picker, no shortcode or custom-emote system, and no Twemoji-style emoji styling. Emoji a user types or pastes pass through as raw, unstyled Unicode, neither encouraged nor blocked — the same posture 4chan itself takes, which renders Unicode but ships no emoji tooling.

This is deliberate. On imageboards the expressive vocabulary is greentext, reaction images, and text faces (kaomoji and ASCII / Shift-JIS art), not graphical emoji. Heavy emoji use reads as an outsider, other-platform, or phone-poster marker, and persistent personal-expression tokens cut against the anonymous, no-personal-branding norm the format depends on. The native surfaces — greentext, image replies, and plain-Unicode text faces — already do what emoji do elsewhere.

It is also strategic. 5chan improves on classic imageboards structurally — independent board ownership, no global admins, the Bitsocial protocol underneath — not by modernizing the posting experience. Imageboard history is consistent: "more modern UX" does not win users and erodes the authenticity that does, and an emoji picker is exactly that kind of modernization. With no global admins to run wordfilters or per-board character rules, the norm holds simply by not building the affordances and by leaving emoji as plain Unicode; board-level moderation can address the rest.

## Design Principles

1. Classic parity first. For boards, threads, posts, replies, catalogs, post forms, navigation, and theme behavior, familiar imageboard behavior is the baseline.
2. Preserve muscle memory. Existing imageboard users should not have to learn new interaction patterns for familiar tasks.
3. Make decentralization invisible until it matters. Board ownership, competing directories, Bitsocial addresses, and moderation differences should be clear when relevant, but should not dominate routine browsing.
4. Custom features inherit the old UI language. Passes, board creation, mod queues, challenges, subscriptions, and directory competition should use compact, flat, text-first imageboard patterns.
5. Favor density over polish. The interface should optimize for scanning, comparison, and repeated use, not marketing impact.

## Accessibility & Inclusion

Keep the nostalgic interface, but do not use nostalgia as an excuse for broken accessibility. Preserve keyboard access, readable focus states, sufficient contrast within each theme, reduced-motion safety, predictable tab order, and responsive behavior on mobile.

When accessibility improvements conflict with exact visual parity, choose the smallest adjustment that fixes the usability issue while preserving the classic imageboard feel.
```

---

## DESIGN.md

Source: https://github.com/bitsocialnet/5chan/blob/master/DESIGN.md

```markdown
---
version: alpha
name: 5chan
description: A decentralized imageboard with a classic imageboard user experience.
colors:
  yotsuba-body-bg: "#ffffee"
  yotsuba-reply-bg: "#f0e0d6"
  yotsuba-mobile-reply-bg: "#f5e9e1"
  yotsuba-border: "#d9bfb7"
  yotsuba-title: "#880000"
  yotsuba-link: "#0000ee"
  yotsuba-hover: "#ff0000"
  yotsuba-name: "#117743"
  yotsuba-subject: "#cc1105"
  yotsuba-greentext: "#789922"
  yotsuba-b-body-bg: "#eef2ff"
  yotsuba-b-reply-bg: "#d6daf0"
  yotsuba-b-border: "#b7c5d9"
  yotsuba-b-title: "#af0a0f"
  yotsuba-b-link: "#34345c"
  futaba-body-bg: "#ffffee"
  modal-preview-bg: "#181f24"
  neutral-white: "#ffffff"
  neutral-black: "#000000"
typography:
  board-title:
    fontFamily: "Tahoma, sans-serif"
    fontSize: "28px"
    fontWeight: 700
    lineHeight: 1.2
    letterSpacing: "normal"
  body:
    fontFamily: "Arial, Helvetica, sans-serif"
    fontSize: "13px"
    fontWeight: 400
    lineHeight: 1.3
    letterSpacing: "normal"
  form-label:
    fontFamily: "Arial, Helvetica, sans-serif"
    fontSize: "10pt"
    fontWeight: 700
    lineHeight: 1.2
    letterSpacing: "normal"
  mobile-post:
    fontFamily: "Arial, Helvetica, sans-serif"
    fontSize: "11pt"
    fontWeight: 400
    lineHeight: 1.3
    letterSpacing: "normal"
rounded:
  square: "0"
spacing:
  page-edge: "5px"
  field-padding: "2px"
  compact-padding: "0.5em"
  hairline: "1px"
components:
  desktop-text-button:
    textColor: "{colors.yotsuba-link}"
    typography: "{typography.body}"
    rounded: "{rounded.square}"
    padding: "0"
  mobile-button:
    backgroundColor: "{colors.yotsuba-reply-bg}"
    textColor: "{colors.yotsuba-title}"
    typography: "{typography.form-label}"
    rounded: "{rounded.square}"
    padding: "3px 5px"
  input:
    backgroundColor: "{colors.neutral-white}"
    textColor: "{colors.neutral-black}"
    typography: "{typography.body}"
    rounded: "{rounded.square}"
    padding: "2px"
  reply-surface:
    backgroundColor: "{colors.yotsuba-reply-bg}"
    textColor: "{colors.yotsuba-title}"
    rounded: "{rounded.square}"
---

## Overview

**Creative North Star: "The Preserved Imageboard"**

5chan's visual system is intentionally conservative. The product should feel like a classic imageboard with a decentralized substrate, not like a redesigned forum or a modern community platform. The default answer for any board, thread, catalog, post, reply, or post-form UI is to preserve familiar imageboard density, typography, color, and interaction shape.

Most surfaces are flat, compact, text-first, and visibly old web. Controls may look plain by modern standards because that plainness is part of the product promise. New decentralized features should enter through the same visual language: small links, square fields, compact tables, simple modal bars, terse labels, and theme-aware colors.

**Key Characteristics:**

- Dense layouts with minimal padding.
- Square edges and 1px borders.
- Arial/Helvetica body text with Tahoma board titles.
- Yotsuba, Yotsuba B, and Futaba-style palettes as first-class themes.
- Text links and bracketed actions over large button components.
- Visual compatibility with classic imageboard user expectations.

## Colors

The palette is inherited from classic imageboard themes and should remain recognizable. Use the existing CSS variables in `src/themes.css` as the source of truth for implementation.

### Primary

- **Yotsuba Body** (`#ffffee`): default warm page background for NSFW-style boards.
- **Yotsuba Reply** (`#f0e0d6`): reply containers, modal surfaces, pagination, menu backgrounds, and compact UI panels.
- **Yotsuba Title Red** (`#880000`): board headers, bars, button text, and theme-defining chrome.
- **Yotsuba B Body** (`#eef2ff`): default cool page background for SFW-style boards.
- **Yotsuba B Reply** (`#d6daf0`): reply containers and panel surfaces in the blue theme.

### Secondary

- **Classic Link Blue** (`#0000ee` / `#34345c`): links, post actions, desktop text buttons, and navigational affordances.
- **Hover Red** (`#ff0000` / `#dd0000`): hover states for links and compact actions.
- **Name Green** (`#117743`): poster names and identity markers.
- **Subject Red** (`#cc1105`): post subjects and title emphasis.
- **Greentext** (`#789922`): quote text and imageboard-specific content convention.

### Neutral

- **Black** (`#000000`): body text in light themes and table borders where the original style calls for it.
- **White** (`#ffffff`): homepage boxes, input fields, and legacy modal surfaces where defined by the theme.
- **Hairline Borders** (`#d9bfb7` / `#b7c5d9`): dividers, reply borders, modal edges, pagination, and mobile post separators.
- **Preview Dark** (`#181f24`): catalog and quote preview overlays only.

### Named Rules

**The Theme Fidelity Rule.** Use existing theme variables before adding new colors. If a color is needed for a new feature, derive its role from the closest established imageboard component in the active theme.

**The No Modern Accent Rule.** Do not introduce a new brand accent, gradient palette, neon crypto palette, or marketing color system for core product UI.

**The Functional Color Exception.** Small, deterministic per-entity colors used as data — for example a hashed swatch that gives each connected peer a stable identity — are allowed. Render them as flat, square, small indicators (not gradients, glows, or large fills). This exception is for conveying data, not for decoration or branding.

## Typography

**Display Font:** Tahoma, sans-serif.
**Body Font:** Arial, Helvetica, sans-serif.
**Label/Mono Font:** Use inherited body fonts unless a compact error or technical address requires monospace.

**Character:** Typography should feel like a browser-native imageboard, not a designed publication. Small sizes, simple weights, default line wrapping, and dense text are expected.

### Hierarchy

- **Board Title** (bold, `28px`, Tahoma): board names and top-level board identity.
- **Box Heading** (bold, `131%`, Arial/Helvetica): homepage bars and compact panel headings.
- **Body** (regular, `13px`, Arial/Helvetica): global app text, board chrome, metadata, and link rows.
- **Post Content** (regular, `11pt` on mobile): comment bodies and mobile post content.
- **Form Label** (bold, `10pt`): post form field headers, modal bars, and compact control labels.
- **Small Metadata** (`9pt` to `10pt`): board bars, file info, timestamps, addresses, and post counts.

### Named Rules

**The Browser-Native Rule.** Do not add custom web fonts, variable-font display systems, negative letter spacing, oversized headings, or marketing typography to product surfaces.

## Layout

Layouts are dense, compact, and text-first, mirroring classic imageboard information density. Spacing is small and deliberate rather than generous, and structure comes from tables, inline rows, and slash-separated links instead of large spaced-out cards.

- **Page edge** (`5px`): outer gutters around boards, catalogs, and threads.
- **Field padding** (`2px`): inputs, table cells, and compact controls.
- **Compact padding** (`0.5em`): reply blocks, menus, and small panels.
- **Hairline** (`1px`): borders and separators between rows, posts, and panels.

Desktop and mobile intentionally differ: desktop stays maximally compact, while mobile raises tap-target and text sizes only as much as needed to stay usable and avoid browser zoom.

### Named Rules

**The Density Rule.** When in doubt, choose the more compact layout. Whitespace is not a feature on core imageboard surfaces.

## Elevation & Depth

5chan is flat by default. Depth is conveyed through background color, 1px borders, hard separators, and occasional legacy-style hard shadows on small menus. Avoid soft elevation, glass, blur, ambient shadows, floating cards, and layered dashboard surfaces.

### Shadow Vocabulary

- **Small Legacy Menu Shadow** (`box-shadow: 2px 2px 0 1px rgba(0, 0, 0, .1)`): small popover menus such as compact filters, when a flat border alone is not enough.

### Named Rules

**The Flat Surface Rule.** If a surface can be separated with a border or theme background, do that instead of adding shadow.

## Shapes

5chan is uniformly square. Corner radius is `0` everywhere on product surfaces, and structure comes from 1px theme borders rather than rounding or elevation.

- **Corners:** square (`0` radius) on buttons, inputs, cards, replies, modals, and menus.
- **Borders:** 1px theme border colors (for example Yotsuba `#d9bfb7`, Yotsuba B `#b7c5d9`).
- **Indicators:** functional per-entity swatches render as small flat squares, never rounded chips.

### Named Rules

**The No Rounding Rule.** Do not introduce `border-radius`, pill, capsule, chip, or rounded badge shapes on product UI. A label is square text, not a rounded token.

## Components

### Buttons

- **Shape:** square corners (`0` radius).
- **Desktop:** prefer text links, bracketed actions, or image-backed icon buttons over filled button components.
- **Mobile:** use theme-colored rectangular buttons with compact padding, bold `10pt` text, and existing button fade assets.
- **Hover / Focus:** hover changes color to the theme hover red; focus must stay visible and keyboard accessible.

### Cards / Containers

- **Corner Style:** square.
- **Background:** theme surfaces such as Yotsuba reply, Yotsuba B reply, homepage white, or the active post/mobile background token.
- **Shadow Strategy:** none except the small legacy menu shadow.
- **Border:** 1px theme borders.
- **Internal Padding:** compact, commonly `2px`, `5px`, or `0.5em`.
- **Hover:** do not change a row's or card's background on hover, and do not add CSS transitions or animations to them. Reserve hover feedback for text-link color changes.
- **Inline labels:** plain text, bold for emphasis. Do not wrap labels (tags, statuses, transports, counts) in pill, capsule, chip, or rounded badge shapes; a label is text, not a button.

### Inputs / Fields

- **Style:** square native fields, white or theme-defined background, `1px solid #aaa` by default.
- **Focus:** border shifts to the theme focus color, such as Yotsuba `#ea8`.
- **Sizing:** preserve compact desktop sizes; on mobile, raise text size where needed to prevent browser zoom.

### Navigation

- **Boards bar:** compact slash-separated board links, small text, theme separators, no pill navigation.
- **Pagination:** small flat cells using theme background and border colors.
- **Directory navigation:** preserve classic board code patterns such as `/a/`, `/b/`, and category groupings.

### Posts And Replies

- **Post metadata:** compact inline text, subject red, name green, timestamps, IDs, roles, and action links in the expected order.
- **Replies:** theme-colored blocks with square borders and minimal padding.
- **Greentext and quote links:** preserve classic color behavior and hover states.
- **Media:** thumbnails should fit the existing imageboard layout and should not create modern card previews unless the current surface already uses that pattern.
- **Emoji and text faces:** pass post text through as raw Unicode. Do not add an emoji picker, shortcode/emote system, or Twemoji-style emoji rendering. Kaomoji and ASCII / Shift-JIS art are the native text-face vocabulary; preserve them and their alignment where used. See `PRODUCT.md` → Text and Expression for the rationale.

### Modals And Popovers

- **Style:** compact movable bars, square borders, theme backgrounds, and legacy close icons where available.
- **Copy:** short labels and direct status messages.
- **Behavior:** custom features such as challenges, settings, and posting flows should feel like imageboard utilities, not app dialogs.

## Do's and Don'ts

### Do

- Start UI changes by checking the closest established imageboard behavior and the existing 5chan implementation.
- Preserve theme variables and add new variables only when a new role is genuinely needed.
- Keep layouts dense, square, and text-first.
- Make decentralized concepts understandable without redesigning the familiar browsing flow.
- Verify desktop and mobile because 5chan intentionally has different post and control treatments across viewports.

### Don't

- Do not modernize core imageboard UI for taste.
- Do not add rounded cards, gradient hero areas, glass panels, soft shadows, dark-mode defaults, or large marketing sections to product surfaces.
- Do not use pill, capsule, chip, or rounded badge shapes for labels, tags, statuses, transports, or counts.
- Do not add hover background fills, color fades, or CSS transitions/animations to rows, cards, or list items.
- Do not replace compact text links with large icon-button toolbars unless the existing surface already uses that pattern.
- Do not introduce a new design system that competes with Yotsuba, Yotsuba B, Futaba, or the existing theme variable model.
- Do not make Bitsocial, crypto, or decentralization visuals dominate routine browsing.
- Do not add an emoji picker, emoji shortcode/emote system, or Twemoji-style emoji rendering; emoji pass through as raw Unicode only.
```

---

## src/AGENTS.md

Source: https://github.com/bitsocialnet/5chan/blob/master/src/AGENTS.md

```markdown
# src/AGENTS.md

These rules apply to `src/**`. Follow the repo-root `AGENTS.md` first, then use this file for code inside the application source tree.

- Before adding new state, decide whether it belongs in render, a reusable hook, or a Zustand store. Do not duplicate the same state logic across views.
- Use `@bitsocial/bitsocial-react-hooks` for data access. Do not add data-fetching `useEffect` calls or effects that only synchronize derived state.
- For state/effect/data-flow or rendering-performance changes, review relevant React guidance. Choose checks and browser/viewports using `docs/agent-playbooks/verification.md`; a copy edit alone does not require React Doctor or a full build.
- Prefer extending nearby tests under `src/**/__tests__/` when touching already-covered behavior.

## Module boundaries

`yarn boundaries` (run by `yarn lint`, so also by `yarn agent:verify` and CI) checks these rules over static imports, re-exports, dynamic `import()`, `import.meta.glob()` patterns and stylesheet `@import` rules; `__tests__/` folders and `*.test.*` files are skipped. Fix a reported violation by moving code, not by widening the import. There is no allowlist: if a rule conflicts with the requested change, restructure within scope or raise it with the user rather than editing the checker.

- Dependencies flow one way: `constants`/`data`/`types`/`generated` → `lib`/`plugins` → `stores` → `hooks` → `components` → `views` → the root files (`app.tsx`, `index.tsx`, `bootstrap.ts`, `sw.ts`) and the `e2e/` harnesses. A lower layer never imports a higher one; when a `lib` helper needs a type or function that lives in a hook or component, the shared part belongs in `lib`.
- `views`, `components`, `hooks`, `stores`, `constants`, `data`, `plugins`, `types`, `generated`, `lib`, and every folder directly under `lib` (`lib/utils`, `lib/media-hosting`, ...) are category folders, not modules. A folder inside one (`components/post-form`, `lib/media-hosting/<name>`) is a module, and its subfolders are private to it; a nested folder is likewise private to its parent, so a module reaches its own sub-modules only through their index.
- Import a module only through its `index.ts` (`../../components/post-form`), never its inner files, subfolders, or stylesheets. A file that sits directly in a category folder (`lib/utils/url-utils.ts`, `hooks/use-directories.ts`) and anything under `data/` may be imported directly. Anything used by more than one module lives at category level (`components/<name>`).
- Views never import other views, their stylesheets included. Shared page layout or styles go in a `components/` module.
- Every route target is a top-level view at `views/<name>`. A subfolder of a view is a private section of that view, not a route.
- Keep the import graph acyclic. When two modules need each other, pass the dependency in as a prop or a context provided by the parent, or move the shared part down a layer.
```

---

## scripts/AGENTS.md

Source: https://github.com/bitsocialnet/5chan/blob/master/scripts/AGENTS.md

```markdown
# scripts/AGENTS.md

These rules apply to `scripts/**`. Follow the repo-root `AGENTS.md` first, then use this file for automation and workflow helpers.

- Keep scripts non-interactive and idempotent. Print the command, URL, branch, or path being acted on so failures are diagnosable.
- Use repo-relative paths and environment variables instead of user-specific absolute paths.
- For dev-server helpers, default to `https://5chan.localhost`, but allow a branch-scoped `*.5chan.localhost` route when the launcher is avoiding a Portless name collision. Start the Portless HTTPS proxy on port 443 before registering routes so legacy `~/.portless` state on port 1355 is not reused. Respect the existing `PORTLESS=0` fallback instead of hard-coding alternate ports. For USB Android preview, `scripts/start-android-usb.mjs` mirrors bitsocial-web: `adb reverse` plus Vite on `127.0.0.1`, then `am start` VIEW to open the default browser when the port is listening (disable with `ANDROID_USB_OPEN_BROWSER=0`).
- Keep shell helpers thin. When logic becomes stateful or cross-platform, prefer a Node script.
- `scripts/pw-session.sh` owns the machine-wide Playwright resource lock shared by every worktree and checkout, so its default lock path must stay repository-independent. Keep acquisition atomic, treat `playwright-cli list --all` as the only liveness oracle and leave the lock alone when it cannot be read, require exact-owner release, and close the named browser before normal release; never broaden cleanup to unrelated sessions.
- Git and worktree helpers must validate input and default to safe operations.
- If a helper deletes local branches automatically, document the exact eligibility checks and keep the behavior conservative.
```

---

## docs/agent-playbooks/known-surprises.md

Source: https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/known-surprises.md

```markdown
# Known Surprises

This file tracks repository-specific confusion points that caused agent mistakes.

## Entry Criteria

Add an entry only if all are true:

- It is specific to this repository (not generic advice).
- It is likely to recur for future agents.
- It has a concrete mitigation that can be followed.

If uncertain, ask the developer before adding an entry.

## Entry Template

```md
### [Short title]

- **Date:** YYYY-MM-DD
- **Observed by:** agent name or contributor
- **Context:** where/when it happened
- **What was surprising:** concrete unexpected behavior
- **Impact:** what went wrong or could go wrong
- **Mitigation:** exact step future agents should take
- **Status:** confirmed | superseded
```

## Entries

### 5archive rejects branch-scoped dev origins

- **Date:** 2026-09-13
- **Observed by:** Tommaso + Claude
- **Context:** Browser-verifying `/search/` changes from a task worktree, which the launcher served at a branch-scoped route (`https://codex-feature-search-board-results.5chan.localhost`).
- **What was surprising:** Every `api.5archive.org` request failed in the browser with `net::ERR_FAILED` and `/search/` showed "The search provider is unavailable", while `curl` from the shell answered normally. The indexer only sends `access-control-allow-origin` for `https://5chan.localhost` and `https://5chan.app`, and the launcher picks a branch-scoped portless name for any non-master branch, so a worktree never gets an allowed origin.
- **Impact:** Anything that calls the indexer looks broken in every worktree browser check; an agent can burn time debugging the client or report a working change as failing.
- **Mitigation:** Confirm the cause with `curl -s -D - -o /dev/null -H "Origin: https://<host>" https://api.5archive.org/api/communities | grep -i access-control`. For the browser check, serve the worktree on the canonical route when it is free (`NODE_EXTRA_CA_CERTS=~/.portless/ca.pem corepack yarn exec portless 5chan vite` from the worktree) and open `https://5chan.localhost`; stop that server afterwards. Do not treat the failure as a client bug.
- **Status:** confirmed

### `yarn changelog` regenerates every release and reverts the changelog rebrand

- **Date:** 2026-09-12
- **Observed by:** Claude Opus 5
- **Context:** Preparing the `v0.9.20` release with the `release` skill, which instructs running `corepack yarn changelog`.
- **What was surprising:** The script is `conventional-changelog -p angular -i CHANGELOG.md -s -r 0`. The `-r 0` flag regenerates *every* release section from raw commit messages, not just the new one. Commit `cdfeb13` had hand-edited 90 lines of `CHANGELOG.md` to scrub pre-rebrand terminology (`subplebbit` -> `community`, `plebbit-js` -> `bitsocial-js`, `Plebbit.` -> `Bitsocial.`), and those edits exist only in the file: the underlying commit subjects still carry the old words.
- **Impact:** Running the documented command reintroduces 45 `plebbit`/`subplebbit` references into historical entries, silently undoing the rebrand inside the release commit itself. Confirmed by diffing a dry run against the committed file.
- **Mitigation:** Do not run `corepack yarn changelog` as-is. Generate only the new section with `corepack yarn exec conventional-changelog -p angular` (no `-i`, `-s` or `-r`), prepend it to `CHANGELOG.md`, then verify the untouched remainder is byte-identical to the previous file before committing. The generated section already ends with the three blank lines the file uses between releases, so plain concatenation preserves the format. The durable fix is to drop `-r 0` from the `changelog` script in `package.json` so it only ever prepends.
- **Status:** confirmed

### AI hook payloads and concurrent locale writes need behavioral checks

- **Date:** 2026-09-11
- **Observed by:** contributor + Codex
- **Context:** Approved audit of the repository's AI workflows for GPT-6 Astra.
- **What was surprising:** Mirrored hook files passed parity checks while Codex supplied patch text in `tool_input.command`, not `file_path`. Stop hooks also mutated Git and repeated builds. Per-key translator agents rewrote the same locale files concurrently.
- **Impact:** Edit hooks could silently skip work; routine conversations could trigger unrelated work; overlapping locale writers could lose keys.
- **Mitigation:** Keep only the payload-tested formatter on edit events, use explicit `agent:verify`, and apply translation maps serially with the writer lock. Run `ai-workflow:test` as well as schema/generated-file checks after workflow changes.
- **Status:** confirmed

### Yarn Berry never runs `pre*`/`post*` hooks on user-defined scripts

- **Date:** 2026-09-02
- **Observed by:** Tommaso + Claude
- **Context:** Investigating why the vendored directory mirror in `src/data/5chan-directories/` went stale (it lacked `/r/` until a manual `yarn sync:directories`) even though `package.json` had `prebuild`/`prestart` entries that called `sync:directories` and `generate:assets`.
- **What was surprising:** This repo uses Corepack-managed Yarn 4 (Berry), which by design does not run npm-style `pre<script>`/`post<script>` hooks for user-defined scripts; it only honours `preinstall`/`install`/`postinstall`, `prepack`/`postpack`, and `prepublish`. `yarn build` went straight to `vite build` and `yarn start` straight to the dev server, so the "automatic" sync and asset generation never ran locally, in CI, on Vercel, or in Electron/Android builds. The entries still work when invoked by name (`yarn run prebuild`), which makes them look alive.
- **Impact:** The committed mirror is exactly what ships; upstream directory changes only reached users when someone ran the sync by hand. Any future `pre*`/`post*` entry for a custom script is silently ignored the same way.
- **Mitigation:** Compose lifecycle intent explicitly: `refresh:generated` runs `sync:directories` and `generate:assets`, and `build` and `start` invoke it as their first step (`corepack yarn refresh:generated && ...`); `scripts/start-android-usb.mjs` calls the same script. Never add `pre*`/`post*` entries for custom scripts in this repo; chain the step into the script itself or into the orchestrating Node script.
- **Status:** confirmed

### Agent verification can saturate contributor laptops

- **Date:** 2026-08-26
- **Observed by:** Tommaso + Codex
- **Context:** Verifying a reply-loading fix while multiple 5chan worktrees already had Vite servers running.
- **What was surprising:** The full Vitest suite started a coordinator plus four Node workers, and subsequent build and React Doctor work ran while existing dev servers remained active. Even sequential heavy commands can saturate several CPU cores when they stack on long-lived worktree servers.
- **Impact:** The contributor laptop became nearly unresponsive for a short period, with several Node processes each consuming close to or more than one CPU core.
- **Mitigation:** Before heavy verification, inspect existing repo processes; remember that `create-task-worktree.sh` automatically installs dependencies; reuse or stop only agent-owned dev servers; cap agent-invoked Vitest at two workers; run worktree creation/installs, full tests, coverage, builds, React Doctor, Electron/Android work, and browser/profiler checks sequentially across all agents; and clean up every process/session the agent starts.
- **Status:** confirmed

### GitHub Projects are not used for repository workflow

- **Date:** 2026-07-23
- **Observed by:** Tommaso + Claude
- **Context:** porting the `review-and-merge-pr` skill fix from `bitsocial-react-hooks` after a merged PR was finalized against a project board
- **What was surprising:** the `review-and-merge-pr` and `make-closed-issue` skills still referenced an organization project and project item even though this repository no longer uses GitHub Projects.
- **Impact:** agents can waste time querying a nonexistent project or report a successful merge as incomplete.
- **Mitigation:** keep pull-request review and merge workflows independent of GitHub issues and Projects; only create or manage an issue when the user explicitly requests one.
- **Status:** confirmed

### react-doctor score reflects React-Compiler coverage, not code health — do not chase it

- **Date:** 2026-06-05
- **Observed by:** Tommaso + Claude
- **Context:** Trying to raise the `yarn doctor` (react-doctor) score to 90 (PR #1155).
- **What was surprising:** The score is overwhelmingly driven by React-Compiler *optimizability* diagnostics, not code quality. Most of the ~92 "errors" are the `react-hooks-js` plugin flagging valid, idiomatic code the React Compiler (v1.0) cannot optimize *yet* — `refs` (the deliberate latest-ref idiom for a stable callback) and `todo` (`try/finally` and throw-in-`try/catch` the compiler can't lower). The score also saturates on the *fraction of files with zero diagnostics*: removing 150 warnings moved it +1; suppressing all 76 compiler-bailout errors reached only 63; only suppressing essentially every rule reaches 90.
- **Impact:** Agents/contributors can burn large effort (and risk real regressions) "fixing" the score by rewriting correct code into compiler-friendly-but-worse shapes, or by suppressing rules until the badge is meaningless. ~63 is the honest, no-regression ceiling.
- **Mitigation:** Do NOT treat the aggregate react-doctor score as a target to grind up (the README badge was removed for this reason). Use react-doctor as a PR-diff reviewer — `yarn doctor --scope changed --base <base> --annotations`, already wired in `.github/workflows/react-doctor.yml` (releases use `yarn doctor --diff <previous tag>` in `release.yml`) — to catch *newly introduced* issues. `doctor.config.jsonc` deliberately does not enforce the `react-hooks-js` rules or `react-compiler-no-manual-memoization` (intentional patterns / current compiler limits). Only fix genuine bugs (e.g. clean `no-adjust-state-on-prop-change` cases). Full reasoning: `docs/agent-runs/react-doctor-score/`.
- **Status:** confirmed

### Portless 0.11 reuses legacy proxy state unless the launcher forces HTTPS

- **Date:** 2026-04-28
- **Observed by:** Tommaso + Codex
- **Context:** Upgrading the normal `yarn start` flow from the old `http://5chan.localhost:1355` proxy URL to `https://5chan.localhost`.
- **What was surprising:** Even with `portless@0.11.1` installed, Portless reused the existing `~/.portless/proxy.port = 1355` HTTP proxy and printed the legacy `:1355` URL.
- **Impact:** Updating package versions and docs is not enough; `yarn start` can still advertise and use the old URL when a contributor has legacy Portless state running.
- **Mitigation:** Keep `scripts/start-dev.js` explicitly starting the Portless HTTPS proxy on port `443` before registering the app route, so the runtime flow migrates away from persisted `1355` state instead of inheriting it.
- **Status:** confirmed

### Android release signing still uses legacy keystore names

- **Date:** 2026-04-23
- **Observed by:** Codex
- **Context:** Cutting the `v0.8.0` release after the core terminology rename changed release workflow signing references.
- **What was surprising:** The tracked Android release keystore and its GitHub secret still carried pre-rebrand names; changing only the workflow references to the rebranded names made the Android release artifact fail at signing.
- **Impact:** Tag releases can pass the Android build and then fail before publishing because `apksigner` cannot find the keystore or password secret.
- **Mitigation:** The tracked keystore is now `android/bitsocial.keystore`, the workflow reads `BITSOCIAL_KEYSTORE_PASSWORD`, and that secret was finally created on 2026-09-12 while cutting `v0.9.20`. The entry was marked resolved on 2026-04-23 when only the file and workflow references had been migrated, so the outstanding half stayed invisible for four months and two releases. Verify a renamed secret with `gh secret list` before claiming a signing migration is complete: a secret value cannot be read back through any API or token scope, so only the owner can create the replacement. The lesson generalises: migrate the tracked file, the workflow path, and the GitHub secret in one change, never the references alone, and do not mark such an entry resolved until every half is verified.
- **Status:** confirmed

### 5chan consumes a pinned hooks tarball instead of using the local hooks repo

- **Date:** 2026-04-15
- **Observed by:** Codex
- **Context:** Debugging strict `{name, publicKey}` community refs after upstream fixes landed in `bitsocial-react-hooks`
- **What was surprising:** 5chan does not consume the nearby `/Users/Tommaso/Desktop/bitsocial/bitsocial-react-hooks` checkout by default; `package.json` installs a pinned GitHub tarball of `@bitsocialnet/bitsocial-react-hooks`.
- **Impact:** Agents can wrongly assume local hooks source changes are already active in 5chan, or debug the wrong package build when the app is really running a tarball revision from GitHub.
- **Mitigation:** Before debugging hooks behavior from 5chan, check `package.json` to see whether the app points at a tarball commit or a local path. If you need fresh hooks behavior, update the tarball commit or temporarily switch 5chan to a local path intentionally.
- **Status:** superseded — `package.json` now installs `@bitsocial/bitsocial-react-hooks` from npm (e.g. `0.1.26`), not a GitHub tarball. The general advice (check `package.json` before assuming local hooks changes are active) still applies.

### Hooks source commits can land before the generated tarball payload

- **Date:** 2026-04-18
- **Observed by:** Codex
- **Context:** 5chan CI failed after `expandTimeWindow` landed in `bitsocial-react-hooks` because the app was pinned to the feature source commit.
- **What was surprising:** `bitsocial-react-hooks` uses `dist/` as its published entrypoint, and the repo's CI writes that generated payload in a follow-up `chore(ci): update dist and coverage badge` commit after the source commit lands on `master`.
- **Impact:** Pinning 5chan to the feature source SHA can install a tarball whose runtime and typings still omit the new API, causing downstream type errors even though the hooks repo's source and CI look green.
- **Mitigation:** When updating 5chan to a new hooks change, verify whether hooks `master` has a newer follow-up `chore(ci): update dist and coverage badge` commit and pin 5chan to that dist-synced SHA rather than the source-only SHA.
- **Status:** superseded — 5chan now consumes `@bitsocial/bitsocial-react-hooks` as a published npm version, so tarball-SHA pinning mechanics no longer apply.

### Portless breaks Windows installs

- **Date:** 2026-03-04
- **Observed by:** Codex
- **Context:** GitHub Actions `Test Windows` dependency install on `windows-2022`
- **What was surprising:** `portless@0.5.2` is a local dev-only tool, but keeping it in `devDependencies` makes `yarn install` fail on Windows because the package declares `win32` unsupported.
- **Impact:** Windows CI fails before build steps run, even though the app does not need `portless` there.
- **Mitigation:** Keep `portless` in `optionalDependencies` and make `yarn start` fall back to direct `vite` startup when `portless` is unavailable.
- **Status:** confirmed

### Electron RPC uses direct pkc-js imports

- **Date:** 2026-03-07
- **Observed by:** Codex
- **Context:** The desktop bootstrap now imports `@pkcprotocol/pkc-js/rpc` directly from `electron/start-pkc-rpc.js`.
- **What was surprising:** Most app data access still goes through `@bitsocialnet/bitsocial-react-hooks`, but the Electron-local RPC bootstrap is intentionally a direct `pkc-js` integration.
- **Impact:** Agents may try to route Electron RPC back through hooks, or reintroduce the legacy protocol package name while fixing dependency/tooling warnings.
- **Mitigation:** Keep Electron RPC on direct `@pkcprotocol/pkc-js` imports. If `knip` flags `electron/start-pkc-rpc.js`, audit the actual dependency graph before adding ignores or legacy packages.
- **Status:** confirmed

### Electron packaging can ship a broken `better-sqlite3` binary

- **Date:** 2026-03-17
- **Observed by:** Codex
- **Context:** Investigating the `v0.7.1` macOS arm64 DMG after the app showed a live IPFS node but never loaded boards or comments.
- **What was surprising:** The packaged app can start IPFS successfully while `electron/start-pkc-rpc.js` loops forever because `/Applications/5chan.app/.../better_sqlite3.node` was built for plain Node 22 (`NODE_MODULE_VERSION 127`) instead of Electron 36 (`NODE_MODULE_VERSION 135`).
- **Impact:** The local RPC server on `ws://localhost:9138` never starts, so the desktop app cannot load boards, posts, or comments even though node stats look healthy.
- **Mitigation:** Before any Electron package/build job, run `yarn electron:prepare-package` so `better-sqlite3` is rebuilt for Electron and immediately verified via `ELECTRON_RUN_AS_NODE=1 electron`.
- **Status:** confirmed

### Plain Vite fallback used to hard-fail on port 1355

- **Date:** 2026-03-30
- **Observed by:** Codex
- **Context:** Running `PORTLESS=0 yarn start` while another local service already owned port `3000`
- **What was surprising:** The non-Portless dev fallback forced Vite onto `5chan.localhost` with `--strictPort`, so the fallback path could fail immediately even though the main Portless flow is collision-safe.
- **Impact:** Contributors could lose the fallback dev path or interrupt their startup flow when `3000` was already busy.
- **Mitigation:** Keep the fallback behind `scripts/start-dev.js`, which now probes from `3000` upward and starts Vite on the next free port instead of exiting.
- **Status:** confirmed

### Fixed Portless app names collide across 5chan worktrees

- **Date:** 2026-03-30
- **Observed by:** Codex
- **Context:** Starting `yarn start` in one 5chan worktree while another 5chan worktree was already serving through Portless
- **What was surprising:** Using the literal Portless app name `5chan` in every worktree makes the route itself collide, even when the backing ports are different, so the second process fails with `"5chan.localhost" is already registered`.
- **Impact:** Parallel 5chan branches can block each other even though Portless is meant to let them coexist safely.
- **Mitigation:** Keep Portless startup behind `scripts/start-dev.js`, which now uses a branch-scoped `*.5chan.localhost` route outside the canonical case and automatically increments a `-2`, `-3`, ... suffix when that branch-scoped route is already occupied.
- **Status:** confirmed

### Toolchain model names and inheritance are not interchangeable

- **Date:** 2026-04-08
- **Updated:** 2026-07-10
- **Observed by:** contributor + Codex
- **Context:** Reviewing repo-managed agent configs under `.codex/agents`, `.cursor/agents`, and `.claude/agents`
- **What was surprising:** Model names remain harness-specific, while Codex custom-agent `model` and `model_reasoning_effort` settings are optional and inherit from the parent when omitted; Codex does not document a `latest` alias for these files.
- **Impact:** Hard-coded Codex model or reasoning-effort settings can become stale or unsupported and prevent subagents from following the contributor's current parent configuration.
- **Mitigation:** Keep `.cursor` agents on Cursor-supported models, never use `composer-2` in `.claude`, and omit `model` and `model_reasoning_effort` from committed custom-agent TOMLs under `.codex/**/agents/*.toml`; `yarn ai-workflow:check` rejects pins so Codex agents keep inheriting parent settings.
- **Status:** confirmed

### codesign parses "5chan.app" as process ID 5

- **Date:** 2026-06-12
- **Observed by:** contributor + Claude
- **Context:** Running the first signed + notarized mac Electron build (`yarn electron:build:mac:arm64` with Apple credentials set)
- **What was surprising:** `@electron/notarize` 2.x runs its pre-upload signature check as `codesign -dv 5chan.app` from the bundle's parent directory, and `codesign` accepts a process ID in place of a path — so it parses the digit-leading basename as PID 5 and fails with `5chan.app: No such process` even though the app is signed correctly.
- **Impact:** Notarization aborts after a successful signing pass; the error message looks like a signing failure and invites debugging the certificate/keychain instead of the real cause. Any tool that shells out to `codesign` with a bare relative path can hit this because the app is literally named `5chan`.
- **Mitigation:** Keep the yarn patch `.yarn/patches/@electron-notarize-npm-2.5.0-*.patch` (backport of electron/notarize#245, prefixes the basename with `./`) until electron-forge depends on `@electron/notarize` >= 3.x. When invoking `codesign` manually on the app bundle, always use an absolute or `./`-prefixed path.
- **Status:** confirmed
```

---

## docs/agent-playbooks/long-running-agent-workflow.md

Source: https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/long-running-agent-workflow.md

```markdown
# Long-Running Agent Workflow

Use this playbook when work needs durable state across sessions or handoffs. A short task or a single delegated slice does not require these artifacts.

## Goals

- Give each fresh session a fast way to regain context
- Keep work incremental instead of one-shotting a large change
- Catch a broken local baseline before adding more code
- Leave durable artifacts that the next session can trust

## Where to Keep State

- Use `docs/agent-runs/<slug>/` when humans, review bots, or multiple toolchains need the same task state.
- Use a tool-local directory such as `.codex/runs/<slug>/` only when the task state is intentionally local to one workstation or one toolchain.
- Do not hide multi-session shared state in a private scratch file if another contributor or agent will need it later.

## Required Files

Create these files at the start of the long-running task:

- `feature-list.json`
- `progress.md`

Use the templates in `docs/agent-playbooks/templates/feature-list.template.json` and `docs/agent-playbooks/templates/progress.template.md`.

Prefer JSON for the feature list so agents can update a small number of fields without rewriting the whole document.

## Session Start Checklist

1. Run `pwd`.
2. Read `progress.md`.
3. Read `feature-list.json`.
4. Run `git log --oneline -20`.
5. For application behavior work only, use an existing task-worktree server or run `./scripts/agent-init.sh --smoke`. Skip server startup for docs/tooling tasks.
6. Choose exactly one highest-priority item that is still `pending`, `in_progress`, or `blocked`.

If a relevant smoke check fails, establish whether the failure affects the task. Report unrelated baseline failures; do not expand scope automatically. Record and clean up any server started for the task.

## Session Rules

- Work on one feature or task slice at a time.
- Keep the feature list machine-readable and stable. Update status, notes, files, and verification fields instead of rewriting unrelated items.
- Only mark an item verified after running the command or user flow listed in that item.
- Use spawned agents for bounded slices, not for overall task-state ownership.
- When a child agent owns one item, give it the exact item id, acceptance criteria, and files it may touch.

## Session End Checklist

1. Append a short progress entry to `progress.md`.
2. Update the touched item in `feature-list.json`.
3. Record the exact commands run for verification.
4. Capture blockers, follow-ups, and the next best item to resume.

## Recommended Progress Entry Shape

Use a short structure like:

```markdown
## 2026-03-17 14:30

- Item: F003
- Summary: Updated the browser-check flow to use the shared init/bootstrap path.
- Files: `.agents/roles/browser-check.md` and generated harness agent files
- Verification: affected checks and their outcomes (use `yarn agent:verify` when a full pass is required)
- Next: Run the smoke flow and update the task-board status.
```
```

---

## docs/agent-playbooks/bug-investigation.md

Source: https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/bug-investigation.md

```markdown
# Bug Investigation Workflow

Use this when a bug is reported in a specific file/line/code block.

## Mandatory First Step

Before editing, check git history for the relevant code. Previous contributors may have introduced behavior for an edge case/workaround.

## Workflow

1. Scan recent commit titles (titles only) for the file/area:

```bash
# Recent commit titles for a specific file
git log --oneline -10 -- src/components/post-desktop/post-desktop.tsx

# Recent commit titles for a specific line range
git blame -L 120,135 src/components/post-desktop/post-desktop.tsx
```

2. Inspect only relevant commits with scoped diffs:

```bash
# Show commit message + diff for one file
git show <commit-hash> -- path/to/file.tsx
```

3. Continue with reproduction and fix after understanding the history context.

## Troubleshooting Rule

Search current documentation or upstream issues when the blocker concerns a dependency or platform behavior. If access to private source or a user-only reproduction step is missing, report that specific gap instead of doing an unrelated web search.
```

---

## docs/agent-playbooks/translations.md

Source: https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/translations.md

```markdown
# Translations Workflow

Locales live in `public/translations/{lang}/default.json`. Use the `translate` skill and `scripts/update-translations.js`; do not rewrite individual locale files by hand.

## Add or update

Create one task-specific temporary map per key, containing every supported language including English. Preserve placeholders, markup, technical terms, and brand names. Discover the supported language directories instead of hard-coding a count.

Translation generation can run in parallel. Only the parent/writer applies the resulting maps, serially:

```bash
node scripts/update-translations.js --key my_new_key --map /tmp/task-key-map.json --include-en --dry
node scripts/update-translations.js --key my_new_key --map /tmp/task-key-map.json --include-en --write
```

Review the dry run and validate the final key/language coverage. Delete only the temporary maps created for this task. A translator child generates its assigned map and returns it; it never invokes a locale write.

## Concurrency and recovery

Every non-dry write mode takes `public/translations/.update-translations.lock` before reading files. A competing writer fails without writing; retry after the owner finishes so it reads fresh state. Each locale file is replaced atomically, but a multi-language operation is not a transaction across all files; inspect results after an interrupted write and safely rerun the intended operation.

Normal success/failure releases the owned lock. A terminated process may leave a lock behind. The lock file has no owner metadata: inspect running translation commands and open file handles to confirm no writer is active before removing that exact stale lock. Never remove a live or unknown lock and never commit lock or temporary files. Dry runs acquire no lock and change no files.

## Other operations

```bash
# Technical term, brand, or placeholder fallback only
node scripts/update-translations.js --key some_key --from en --dry
node scripts/update-translations.js --key some_key --from en --write

# Authorized key removal
node scripts/update-translations.js --key obsolete_key --delete --dry
node scripts/update-translations.js --key obsolete_key --delete --write

# Inspect unused keys before an authorized removal
node scripts/update-translations.js --audit --dry
node scripts/update-translations.js --audit --write
```
```

---

## docs/agent-playbooks/skills-and-tools.md

Source: https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/skills-and-tools.md

```markdown
# Skills and Tools

Shared skills live in `.agents/skills/`. Edit these sources, then run `yarn ai-workflow:sync` to generate `.claude/skills/` for Claude Code. Codex and Cursor discover `.agents/skills/` directly; do not restore the duplicate `.codex/skills/` or `.cursor/skills/` roots.

Shared role prompts live in `.agents/roles/*.md`. This is a repository-specific source format, not a native agent discovery path. `scripts/ai-workflow-files.mjs` converts these sources into the app-specific files below; `yarn ai-workflow:sync` writes them. Commit the generated files alongside their sources so a fresh checkout has the native configuration without running a generator first. After removing a source, remove its obsolete generated outputs explicitly; the validator reports them rather than silently deleting files.

## Native discovery paths

Verified against official documentation on 2026-09-12:

| App | Project instructions | Skills used by this repository | Custom agents used by this repository |
|---|---|---|---|
| Codex | `AGENTS.md` | `.agents/skills/<name>/SKILL.md` | Generated `.codex/agents/<name>.toml` |
| Cursor | `AGENTS.md`; `.cursor/rules/*.mdc` remains available for Cursor-specific conditional rules | `.agents/skills/<name>/SKILL.md` | Generated `.cursor/agents/<name>.md` |
| Claude Code | `CLAUDE.md` imports `@AGENTS.md` | Generated `.claude/skills/<name>/SKILL.md` | Generated `.claude/agents/<name>.md` |

Sources: [Codex skills](https://learn.chatgpt.com/docs/build-skills), [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents), [Cursor rules](https://cursor.com/docs/rules), [Cursor skills](https://cursor.com/docs/skills), [Cursor subagents](https://cursor.com/docs/subagents), [Claude memory](https://code.claude.com/docs/en/memory), [Claude skills](https://code.claude.com/docs/en/skills), [Claude subagents](https://code.claude.com/docs/en/sub-agents).

Do not replace the native agent directories with `.agents/roles` or assume Claude discovers `.agents/skills`. Claude can still read a referenced file there as ordinary project context. Cursor also discovers `.claude/skills` for compatibility; copies remain synchronized, but its published skills guide does not specify deduplication across these roots. Check the installed app's skill catalog rather than promising that duplicate entries cannot appear.

The AI directories use LF line endings through `.gitattributes` so generated text stays identical across platforms. Supporting skill assets are copied as bytes.

## Skills

| Skill | Purpose |
|---|---|
| `commit` | Create authorized, scoped local commits |
| `commit-format`, `issue-format` | Format suggestions when requested |
| `make-closed-issue` | Create an authorized issue, scoped commit and PR |
| `review-and-merge-pr` | Triage PR feedback; fix/publish/merge only within the requested scope |
| `fix-merge-conflicts` | Resolve conflicts and verify the merged result |
| `release`, `release-description` | Prepare release wording and perform authorized release steps |
| `code-quality-review` | Review non-trivial diffs or an explicitly requested quality concern |
| `retro` | Turn demonstrated mistakes into focused checks or review guidance |
| `refactor-pass`, `deslop` | Requested cleanup of existing changes |
| `debug-agent` | Evidence-based debugging, with instrumentation when needed |
| `you-might-not-need-an-effect` | Focused effect/memo review |
| `vercel-react-best-practices` | Applicable React performance guidance; skip Next.js/server-only rules for this Vite client |
| `translate` | Generate translations, then apply maps through a single writer |
| `playwright-cli`, `inspect-elements` | Browser verification and DOM-to-source mapping |
| `profile-browsing` | Scoped browser and React profiling |
| `test-apk` | Local Android emulator procedures |
| `implement-plan` | Execute a plan with optional bounded delegation |
| `readme` | Maintain verified project documentation |
| `context7` | Retrieve version-appropriate library documentation |
| `find-skills` | Find additional skills when explicitly requested |

## Roles and models

Keep custom roles for `browser-check`, `profiler`, `test-apk`, `translator`, and `reviewer`. Use the harness's built-in worker/general-purpose or explorer role for ordinary implementation and code discovery. The parent assigns acceptance criteria and ownership; one owner runs heavyweight checks.

Codex agent files include `name`, `description`, and `developer_instructions`. `.codex/config.toml` caps concurrent children at four using `max_concurrent_threads_per_session`. Shared role metadata contains the name, description, and optional sandbox mode; it deliberately has no model fields.

Leave model and reasoning fields out of committed skills and custom agents in all three apps. This allows runtime invocation choices, user defaults, and parent inheritance according to each app’s documented precedence. Claude family aliases reduce version maintenance but still choose a family; a versioned Cursor model requires future updates. Keep such choices in user/session settings when needed. Inheritance does not promise an automatic choice of the best current model. Do not invent a `latest` alias or add model-catalog research to routine tasks. See [Codex selection](https://learn.chatgpt.com/docs/agent-configuration/subagents), [Claude selection](https://code.claude.com/docs/en/sub-agents#choose-a-model), and [Cursor selection](https://cursor.com/docs/subagents#model-configuration).

`sandbox-mode: read-only` maps to Codex’s sandbox and Cursor’s `readonly`; Claude’s tool list and the role instructions restrict its review workflow, but Bash access is not an OS-level sandbox.

Shared skill frontmatter uses `disable-model-invocation: true` for user-invoked workflows where applicable. Codex's corresponding setting lives in `agents/openai.yaml` as `policy.allow_implicit_invocation: false`; the validator requires both. Invocation metadata supplements explicit authorization rules; a review request never authorizes publication merely because a skill includes publishing steps.

## Checks and discovery

- `yarn ai-workflow:sync` regenerates compatibility outputs using installed `js-yaml` and `smol-toml`.
- `yarn ai-workflow:check` parses source/frontmatter/configs, checks generated outputs, invocation metadata, model-field placement, and the formatter-only hook wiring. It does not resolve model identifiers against a provider catalog.
- `yarn ai-workflow:test` runs isolated Node fixtures for hook payloads, verification ownership, translation writers, and workflow generation/validation.
- After upgrading an agent application, verify skill/role discovery in that application. Syntax/parity checks do not replace a loader check. Reload the application if an existing session retains an old catalog.
- Hooks require the harness's project trust and hook review; do not bypass trust to make a check pass. See [hooks-setup.md](hooks-setup.md).

## Maintaining useful instructions

Follow [OpenAI’s skills and prompts guidance](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra) (reviewed 2026-09-12): keep descriptions precise, load details only when relevant, and preserve the user’s requested scope. Shared skills serve different models; retain project-specific invariants while allowing routine implementation choices.

Keep a skill’s purpose, decision boundaries, and essential constraints in `SKILL.md`. Link substantial mode-specific commands or examples as optional references. Put trigger conditions early in short descriptions; a matching keyword alone should not expand the task. Preserve existing invocation metadata unless its behavior is intentionally being changed.

After a substantial instruction change, exercise a few representative small and large requests. Check which skills/references were selected, whether actions stayed within scope, whether verification matched the change, and whether authorized work completed. Schema and fixture tests establish tooling correctness, not agent decision quality.

## Tools and browser ownership

Prefer the existing skill/tool catalog and installed project CLIs. Use `gh` for GitHub, `playwright-cli` for browser verification, and official/version-specific documentation when library behavior matters. Avoid installing duplicate skills or fetching an unpinned package merely to run an existing formatter.

MCP overhead depends on the harness: deferred tool loading can avoid loading every schema upfront. Keep integrations relevant rather than treating MCP itself as obsolete. Existing CLI choices remain useful for reproducibility and resource control.

All browser sessions use `./scripts/pw-session.sh`, which enforces one active browser machine-wide. Default to a fresh isolated session. Current personal-browser access needs explicit authorization; reuse that authorization in subsequent steps. Choose browsers/viewports for the affected behavior, run selected engines sequentially, close the exact named session in cleanup, and never use `close-all`/`kill-all`. See the `playwright-cli` skill and [verification.md](verification.md).
```

---

## docs/agent-playbooks/verification.md

Source: https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/verification.md

```markdown
# Agent Verification

Choose checks that establish the requested behavior. Finish the authorized implementation and fix failures caused by it; report unrelated failures with evidence. Reuse successful checks for unchanged code instead of starting the same pass again.

## Select checks by impact

| Change | Default verification |
|---|---|
| Prose, comments, or formatting | Inspect the diff and relevant links/output; run required generators. No application build for documentation alone |
| Isolated logic or automation | Affected behavior tests or a focused invocation; lint/type-check when the edited language or interface warrants it |
| Shared runtime behavior, dependencies, build/package configuration, or substantial integration | Focused behavior tests plus `corepack yarn agent:verify` for build, lint, type-check, Doctor diagnostics, and runtime scenarios |
| CSS, themes, or layout only | Affected browser/viewport/theme checks below; add a build for CSS processing, assets/import wiring, or integration uncertainty. Styling alone does not require React Doctor |
| React state/effects/data flow or rendering performance | Inspect the relevant architecture; run `yarn doctor:check` and affected `yarn perf:check` scenarios |
| Dependencies or import graph | `yarn boundaries` (part of `yarn lint`) must pass when `src/` files move or imports change; advisory `yarn knip`; resolve relevant new findings |
| Release, CI, or explicitly requested full verification | Run that workflow's required checks even when a smaller local edit would normally need less |

For a small edit, name the behavior being checked and why the chosen evidence is enough. Broaden checks when the impact crosses a shared boundary, a failure appears, or uncertainty remains. Do not add tests that only mirror wording or formatting. An existing reliable test is preferable to new instrumentation.

For focused Vitest runs use `corepack yarn exec vitest run --maxWorkers=2 [paths]`. Add or extend nearby regression tests for non-trivial, testable bugs. The AI workflow Node tests use disposable fixtures and fake commands without production access; run and repair them within the requested task without another approval pause.

## Browser coverage

Verify the affected flow in Chrome/Blink for a small browser change. Also cover Firefox/Gecko and WebKit/Safari for shared CSS/layout/responsiveness changes, browser-sensitive behavior or APIs, broad interaction changes, releases, or an explicit cross-browser requirement. Include desktop/mobile when layout, responsiveness, or touch behavior is affected. Check changed theme behavior in relevant themes.

Use the `playwright-cli` skill and `./scripts/pw-session.sh` for every session. Run selected engines sequentially and close the exact session in cleanup even if a check fails. Reuse a compatible server in the same worktree or record and stop only the one this task starts. Use a fresh profile unless current-session access is already authorized and required.

For loading, navigation, or interaction performance, add a Chromium low-spec pass with `./scripts/pw-throttle.sh <session> mid`; see [low-spec verification](low-spec-verification.md). Firefox and WebKit remain unthrottled.

## Full verification and ownership

Before heavy work, inspect existing workloads; never stop an unfamiliar process. One owner runs `corepack yarn agent:verify` when a full pass is needed. It serializes build, lint, type-check, Doctor diagnostics, and runtime scenarios behind a machine-wide lock and reports contention. Installs, tests, browser work, and directly launched builds still require coordination.

Builds may refresh generated assets and create `build/`. Inspect status before and after, preserve preexisting artifacts and changes, and remove only output created by this task. The verifier never restores or deletes output for you. No lifecycle hook runs builds, installs, audits, or Git cleanup.

Review the final task-owned diff. For non-trivial changes or an explicit quality review, use `code-quality-review` once and apply high-confidence findings within existing authorization. Passing a check or review does not authorize publication.

## Workflow and document changes

For shared skills, roles, or hooks run `yarn ai-workflow:sync`, `yarn ai-workflow:check`, and `yarn ai-workflow:test`. Run `yarn llms:generate` after public English docs or AI context changes. These checks do not require an app server or browser. When only prose changed, skip the application build; changing executable workflow code may need the focused or full checks above.

After substantial prompt changes, try representative requests for skill selection, scope, completion, and check choice. Use isolated fixtures for actions where possible; a read-only scenario review is useful evidence but does not prove live execution behavior.

Record commands, outcomes, and limits in the task report. Use the [long-running workflow](long-running-agent-workflow.md) only when a durable handoff is needed.

## Automated React performance evidence

Run `yarn perf:install` once for the pinned browser, then `yarn perf:check` (three samples at 4x CPU by default). Scope a rerun with `--scenario <name>` when the change affects one covered flow. CI runs the compatibility self-test and scenarios; local `agent:verify` runs scenarios and Doctor automatically. After React/Bippy/collector upgrades, run `yarn perf:test` before relying on the counts. Keep these heavy checks out of per-edit hooks.

`yarn perf:record` keeps JSON and native trace evidence under `.react-perf/`; use `--url <origin>` to reuse a compatible instrumented server. The runner owns its processes and browser lock; run it separately from manual browser sessions. Scenario configuration lives in `scripts/react-perf/config.mjs`. Exact update limits follow the tested interaction; timing caps are deliberately generous smoke limits and must not be relaxed merely to silence a failure. Diagnose a failed phase from its component-instance/commit evidence and visible completion.

Read the `profile-browsing` measurement reference for interpretation and coverage limits. Root Profiler duration measures the subtree, not the self time of each component. A normal production preview lacks this React instrumentation; build and serve `build-profile/` for production-like React timing, leaving the release output untouched.
```

---

## docs/agent-playbooks/hooks-setup.md

Source: https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/hooks-setup.md

```markdown
# Agent Hooks Setup

The only automatic lifecycle action is formatting edited JavaScript and TypeScript files. Each harness has a thin `format.sh` wrapper that calls `scripts/agent-hooks/format.mjs`. Finishing a response does not install packages, run verification, inject review reminders, or mutate Git state.

## Entry points

| Harness | Entry point | Event |
|---|---|---|
| Claude Code | `hooks` in `.claude/settings.json` | `PostToolUse`, matcher `Edit\|Write\|MultiEdit` |
| Cursor | `.cursor/hooks.json`, version 1 | `afterFileEdit` |
| Codex | `.codex/hooks.json` | `PostToolUse`, matcher `apply_patch` |

Keep these application-specific schemas separate. Codex hooks also need to be trusted in the contributor's Codex settings before they run; a committed configuration does not establish that trust.

## Formatting behavior

- Claude sends `tool_input.file_path`; Cursor sends `file_path`.
- Codex sends `apply_patch` text in `tool_input.command`. The formatter collects added and updated files, uses the destination of a move, and ignores deleted files.
- Relative paths use the payload's working directory when supplied, falling back to the repository root.
- Known read-only tool calls, non-edit events, reported tool failures, malformed input, missing paths, and unsupported extensions are skipped.
- Both lexical paths and resolved real paths must remain inside this checkout. This includes the final file and any symlinked parent directories.
- Formatting runs once per payload through `corepack yarn exec oxfmt --write`, only when the repository's formatter is installed. Corepack network access is disabled. Missing dependencies are not installed by the hook.
- Node command launches use the declared `cross-spawn` dependency to handle Windows command shims and argument escaping. Shell hook entry points still require the harness's Bash support on Windows.
- Formatter failures are reported on stderr and remain advisory. Hooks do not inject additional instructions into the model.

Run `corepack yarn install` explicitly when setting up a worktree or changing dependencies. The worktree creation helper already performs installation.

## Explicit verification

Use `corepack yarn agent:verify` when the change needs the full pass described in [verification.md](verification.md). `scripts/agent-verify.mjs` runs `build`, `lint`, and `type-check` sequentially, prints the commands and working directory, and reports every failed check. It completes the remaining checks after a command fails and exits with the first failure's status. A missing executable returns 127; a terminated command reports its signal and returns the conventional signal exit status.

The command does not remove, restore, or stage generated artifacts. The build itself can update output and generated files; inspect the resulting diff and clean up only output created by your own run. Tests, React Doctor, and browser verification remain explicit checks selected for the change.

All checkouts share an atomic lock directory named `5chan-agent-verify.lock` in the operating system's temporary directory. A busy slot exits immediately with status 75 and owner details. Wait for the owning run to finish before retrying. Normal completion and handled SIGINT/SIGTERM release the lock; on Unix, interruption is forwarded to the active command's process group, and on Windows it terminates the command tree through `taskkill /T /F`. A force-killed process can leave a lock behind. Inspect `owner.json` and verify that the recorded run and its child workloads have stopped before manually removing that stale lock. Unreadable metadata is never treated as permission to steal the slot.

The lock coordinates invocations of this command. Other heavyweight work, such as installs, tests, browsers, and builds launched directly, still needs the repository's workload coordination rules.

## Maintaining the workflow

- Change shared formatter behavior in `scripts/agent-hooks/format.mjs`; keep harness wrappers thin.
- Wire only the formatter in each hook configuration. Dependency installation, Git housekeeping, reviews, and full verification belong to explicit workflows.
- Run `corepack yarn ai-workflow:check` after changing hook scripts or configuration.
- Run `yarn ai-workflow:test` for payload, path-containment, and verification behavior. These tests use fake commands and never run real builds.
```

---

## docs/upload-automation-retest-checklist.md

Source: https://github.com/bitsocialnet/5chan/blob/master/docs/upload-automation-retest-checklist.md

```markdown
# Upload Automation Retest Checklist

Retest checklist for Android and desktop after changes to media upload automation (`MediaUploadAutomationRunner`, `MediaUploadRecipes`, `upload-orchestrator`, etc.).

## Quality Gate (blocking)

Run before merge/rollout. All must pass.

| Command | Purpose | Interpretation |
|---------|---------|----------------|
| `yarn test` | Unit tests (Vitest) | Exit 0 = pass. Fix failing tests before merge. |
| `yarn build` | Production build | Exit 0 = pass. No build errors. |
| `yarn lint` | Lint (oxlint + module boundaries) | Exit 0 = pass. Fix lint errors. |
| `yarn type-check` | TypeScript (tsc) | Exit 0 = pass. Fix type errors. |
| `yarn doctor` | React Doctor | Advisory. Prioritize `error` > `warning`. |

**Quick run (all quality gates):**

```bash
yarn retest:quality
```

---

## Imgur chooser contract (required local gate)

Runs imgur-specific emulator contract tests against deterministic fixtures. **Emulator required.** Must pass before merge.

```bash
yarn contract:imgur
```

- **Prereq:** Android emulator running or USB device connected.
- **Interpretation:** Exit 0 = contract tests pass. Runs `MediaUploadAutomationRunnerTest` (imgur chooser contract + generic fixtures). Uses deterministic fixtures in `android/app/src/main/assets/fixtures/`.

---

## Android Emulator Verification (report-only)

Instrumentation tests run on an **emulator or physical device**. Requires an emulator/device to be running and connected.

### Standard run

```bash
yarn android:connectedTest
```

Or directly (uses UTP workaround for protobuf compatibility):

```bash
cd android && ./gradlew :app:connectedDebugAndroidTest -Pandroid.experimental.androidTest.useUnifiedTestPlatform=false
```

- **Prereq:** Emulator running (`emulator -avd <avd_name>` or Android Studio) or USB device.
- **Interpretation:** Exit 0 = all instrumented tests pass. `MediaUploadAutomationRunnerTest` exercises fixtures in `android/app/src/main/assets/fixtures/`.

### UTP / Protobuf issue (known)

On some setups, `connectedDebugAndroidTest` fails with protobuf classloader conflicts (e.g. `IllegalAccessError` involving `com.google.protobuf.CodedInputStream`). This is a known UTP/Espresso + protobuf incompatibility.

**Workaround (disable UTP, use legacy test runner):**

Use this exact command, which passes `-Pandroid.experimental.androidTest.useUnifiedTestPlatform=false` to disable the unified test platform:

```bash
cd android && ./gradlew :app:connectedDebugAndroidTest -Pandroid.experimental.androidTest.useUnifiedTestPlatform=false
```

> **Caveat:** The `useUnifiedTestPlatform=false` flag may be deprecated in future Android Gradle Plugin versions; if it stops working, use the fallback below.

If the above does not resolve it, exclude conflicting protobuf from Espresso in `android/app/build.gradle`:

```gradle
androidTestImplementation("androidx.test.espresso:espresso-core:3.3.0") {
    exclude group: "com.google.protobuf", module: "protobuf-java"
    exclude group: "com.google.protobuf", module: "protobuf-lite"
}
```

---

## Upload Selector Smoke Run (report-only, non-blocking)

Probes live upload sites (Imgur) to verify selectors in `media-upload-recipes` still match. **Always exits 0**; intended for CI report-only and local triage. **Not a merge gate**—check report for selector drift but do not block.

```bash
yarn smoke:upload-selectors
```

- **Output (report):** `scripts/upload-selectors-smoke-report.json`
- **Output (snapshots):** `scripts/upload-selectors-smoke-snapshots/` (provider PNGs)
- **Interpretation:** Check `summary.ok` vs `summary.warn` in the report. Warnings indicate selectors may need updates; do not block merge without further triage.

---

## Desktop (Electron)

Build and run the Electron app to manually verify upload flows:

```bash
yarn electron:start
```

Unit tests for Electron automation (non-blocking, report-only):

```bash
node electron/media-upload-automation.test.js
node electron/media-upload-recipes.test.js
```

---

## Summary

| Check | Blocking? | Command |
|-------|-----------|---------|
| Quality gate | Yes | `yarn retest:quality` |
| Imgur chooser contract | Yes | `yarn contract:imgur` |
| Android instrumentation | No (report-only) | `yarn android:connectedTest` |
| Upload selector smoke | No (report-only) | `yarn smoke:upload-selectors` |
| Electron unit tests | No (report-only) | `node electron/media-upload-*.test.js` |
```

---