External/5chan
1
0
Fork 0
mirror of https://github.com/bitsocialnet/5chan.git synced 2026-08-03 07:41:04 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(agents): add generated LLM context workflow

Browse Source
This commit is contained in:
Tommaso Casaburi
2026-05-20 14:48:34 +07:00
parent 6a7df90129
commit d6d01c0571
6 changed files with 3328 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public/llms.txt
+38 -155
View File
@@ -1,168 +1,51 @@
# 5chan
5chan is a serverless, adminless, decentralized, open-source imageboard client built on the Bitsocial protocol.
> 5chan is a static, serverless, adminless, decentralized imageboard client built on the Bitsocial protocol.
The canonical web app is https://5chan.app and the source repository is https://github.com/bitsocialnet/5chan.
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`.
## Summary
## Canonical Links
- 5chan.app hosts a static client shell, not board or post content.
- User-generated content is fetched client-side from Bitsocial boards and related peer-to-peer infrastructure, including IPFS-backed data flows.
- Board owners host and moderate their own content. The operator of `5chan.app` does not run a central content backend for boards or threads.
- Hash routing is intentional. It keeps user-generated board and post paths out of server-side routing and out of CDN rewrite logic.
- The project prioritizes censorship resistance, mirrorability, and static-host compatibility over traditional crawlable-route SEO.
- [App](https://5chan.app)
- [Repository](https://github.com/bitsocialnet/5chan)
- [Releases](https://github.com/bitsocialnet/5chan/releases/latest)
- [Bitsocial protocol](https://bitsocial.net)
- [5chan Board Manager](https://github.com/bitsocialnet/5chan-board-manager)
- [Directory list source](https://github.com/bitsocialnet/lists/blob/master/5chan-directories.json)
- [llms-full.txt](https://5chan.app/llms-full.txt): Expanded inline corpus generated from the curated source docs.
## What 5chan Is
## Critical Context
5chan is a decentralized imageboard interface with a familiar directory-style UX. Anyone can create and operate boards using the Bitsocial ecosystem. Multiple boards can compete for a directory slot, while users can still access any board directly by address even if it is not currently assigned to a homepage directory entry.
- 5chan.app serves a static client shell, not board or thread content.
- User-generated board content is fetched client-side from Bitsocial boards and peer-to-peer infrastructure.
- Board owners host and moderate their own content; the app operator does not run a central content backend.
- Do not describe Vercel, a CDN, or the 5chan.app origin as serving user-generated board or thread content.
- Do not propose SSR or server rewrites for board/thread URLs unless a maintainer explicitly asks for that tradeoff.
- Hash routing and static deployment compatibility are intentional product and liability choices.
- Preferred framing: static client, decentralized imageboard client, serverless/adminless interface.
- For code contributions, AGENTS.md and directory-specific AGENTS.md files are the source of truth.
This repository primarily contains the client application. It is a React and TypeScript single-page app that can run as a web app, Electron app, and Android app. The web deployment is intentionally a static app shell that does not centrally host board content.
## Source Of Truth
## Content and Liability Model
- Code, tests, package manifests, source docs, and live/runtime evidence when relevant are source of truth.
- This generated file is compiled context for orientation. Verify behavioral claims against source files before editing or concluding.
- Repo-managed AI instructions live in `AGENTS.md` and any directory-specific `AGENTS.md` files.
- Do not describe 5chan.app as a content host for boards or threads.
- Do not assume Vercel, a CDN, or the `5chan.app` origin serves user-generated thread content.
- Do not propose SSR or server rewrites for board or thread URLs unless a maintainer explicitly asks for that tradeoff.
- Hash routing is a deliberate architectural choice tied to censorship-resistance and liability minimization, not an oversight.
- The project wants a deployable static client that can also be mirrored or self-hosted easily.
## Core Documents
## Canonical Public Links
- [5chan](https://github.com/bitsocialnet/5chan/blob/master/README.md): 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 differenc...
- [AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/AGENTS.md): This file defines the always-on rules for AI agents working on 5chan. Use this as the default policy. Load linked playbooks only when their trigger condition applies.
- [Product](https://github.com/bitsocialnet/5chan/blob/master/PRODUCT.md): product
- [Design System: 5chan](https://github.com/bitsocialnet/5chan/blob/master/DESIGN.md): **Creative North Star: "The Preserved Imageboard"**
- [src/AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/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.
- [scripts/AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/scripts/AGENTS.md): These rules apply to `scripts/**`. Follow the repo-root `AGENTS.md` first, then use this file for automation and workflow helpers.
- [Known Surprises](https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/known-surprises.md): This file tracks repository-specific confusion points that caused agent mistakes.
- [Long-Running Agent Workflow](https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/long-running-agent-workflow.md): Use this playbook when a task is likely to span multiple sessions, handoffs, or spawned agents.
- [Bug Investigation Workflow](https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/bug-investigation.md): Use this when a bug is reported in a specific file/line/code block.
- [Translations Workflow](https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/translations.md): This project uses i18next translation files in `public/translations/{lang}/default.json`.
- [Skills and Tools](https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/skills-and-tools.md): Use this playbook when setting up/adjusting skills and external tooling.
- App: https://5chan.app
- Repository: https://github.com/bitsocialnet/5chan
- Releases: https://github.com/bitsocialnet/5chan/releases/latest
- README: https://github.com/bitsocialnet/5chan/blob/master/README.md
- Agent instructions: https://github.com/bitsocialnet/5chan/blob/master/AGENTS.md
- Bitsocial protocol site: https://bitsocial.net
- 5chan Board Manager: https://github.com/bitsocialnet/5chan-board-manager
- Directory list source: https://github.com/bitsocialnet/lists/blob/master/5chan-directories.json
## Optional
## Architecture
- Frontend stack: React 19, TypeScript, React Router v6, Zustand, Vite, i18next, bitsocial-react-hooks
- Package manager: yarn
- Linting: oxlint
- Type checking: tsgo
- React app entry: `src/index.tsx`
- Static HTML shell and base metadata: `index.html`
- Main route tree: `src/app.tsx`
- Shared UI: `src/components/`
- Route views: `src/views/`
- Shared hooks: `src/hooks/`
- Shared state: `src/stores/`
- Utilities: `src/lib/`
## Important Repository Rules For AI Contributors
These are condensed from `AGENTS.md`. If you are contributing code, follow the repository instructions there as the source of truth.
- Use `yarn`, never `npm`.
- Pin exact dependency versions.
- Keep `yarn.lock` in sync if `package.json` changes.
- Use Zustand for shared or global state.
- Do not use `useEffect` for data fetching; use `bitsocial-react-hooks`.
- Do not sync derived state with effects when render-time computation is sufficient.
- Use React Router for navigation.
- Avoid duplicating logic across components; extract shared hooks when appropriate.
- For bug reports tied to a file or line, inspect git history before editing.
- Never mark work complete without verification.
- After code changes, run `yarn build`, `yarn lint`, and `yarn type-check`.
- After React UI logic changes, also run `yarn doctor`.
- For UI and visual changes, test desktop and mobile behavior with `playwright-cli`.
- Use `gh` CLI for GitHub operations.
- Never push to a remote unless the maintainer explicitly asks.
- Never commit secrets or API keys.
## Local Development
Prerequisites:
- Node.js 22
- Corepack enabled for Yarn 4 (`corepack enable`)
Common setup:
```bash
corepack yarn install
yarn start
```
The normal dev URL is https://5chan.localhost using Portless. First run may prompt for sudo so Portless can bind the HTTPS proxy on port 443.
To bypass Portless:
```bash
PORTLESS=0 yarn start
```
Useful commands:
```bash
yarn build
yarn lint
yarn type-check
yarn doctor
yarn test
yarn electron
```
## Contribution Guidance
Good contributions:
- Bug fixes
- Frontend architecture improvements that preserve the static-client model
- Tests
- Performance improvements
- Translation updates
- Documentation improvements
- Build and release tooling fixes
Be careful with:
- SEO recommendations that assume normal server-rendered routes
- Changes that replace hash routing with server rewrites
- Any approach that makes `5chan.app` appear to serve user-generated board or thread content from its origin
- Suggestions that assume there is a centralized moderation backend
If you are an AI coding agent, read `AGENTS.md` before making non-trivial changes.
## How Boards Work
In the Bitsocial protocol, a board is a community. Board operators run their own infrastructure and moderation. Users access boards through addresses rather than a central database owned by 5chan. Directory presence on the 5chan homepage is a discovery layer, not proof of central hosting or ownership.
Boards can be submitted for directory inclusion by editing the list maintained at:
https://github.com/bitsocialnet/lists/blob/master/5chan-directories.json
## Preferred Framing
When describing 5chan, prefer language like:
- "static client"
- "decentralized imageboard client"
- "serverless, adminless interface"
- "board content is hosted and moderated by board operators"
- "5chan.app distributes the app shell, not centralized board content"
Avoid language like:
- "5chan hosts all posts"
- "5chan serves board pages from its server"
- "Vercel hosts 5chan content"
- "5chan is a centralized forum backend"
## Maintainer Intent
The project values:
- Censorship resistance
- Easy mirroring and self-hosting
- Static deployment compatibility
- Avoiding centralized control over board content
- A contributor workflow that is strict about verification and repo-specific instructions
For deeper contributor guidance, read:
- https://github.com/bitsocialnet/5chan/blob/master/AGENTS.md
- https://github.com/bitsocialnet/5chan/blob/master/README.md
- [Changelog](https://github.com/bitsocialnet/5chan/blob/master/CHANGELOG.md): * **blotter:** render on multiboard feeds ([918ed5b](https://github.com/bitsocialnet/5chan/commit/918ed5b11b0ef7c2a982725077575d91853ed0f0)) * **boards bar:** preserve catalog multiboard links ([29f5e67](https://githu...
- [Upload Automation Retest Checklist](https://github.com/bitsocialnet/5chan/blob/master/docs/upload-automation-retest-checklist.md): Retest checklist for Android and desktop after changes to media upload automation (`MediaUploadAutomationRunner`, `MediaUploadRecipes`, `upload-orchestrator`, etc.).