Hoppa till huvudinnehåll

Kända överraskningar

Den här filen samlar repospecifika förvirringspunkter som har lett till agentmisstag.

Kriterier för poster​

Lägg bara till en post om allt nedan stämmer:

  • Den är specifik för det här repot (inte allmänna råd).
  • Den kommer sannolikt att återkomma för framtida agenter.
  • Den har en konkret åtgärd som går att följa.

Om du är osäker, fråga utvecklaren innan du lägger till en post.

Mall för poster​

### [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

Poster​

Produktionsdomäner för Vercel-appar kan glida tillbaka till distributioner från Git-grenen master​

  • Datum: 2026-04-28
  • Observerad av: Tommaso + Codex
  • Sammanhang: Verifiering av app-speglarna för Seedit och 5chan i Bitsocial Webs appkatalog.
  • Det överraskande: Vercel-projekten seedit och 5chan hade gitProviderOptions.createDeployments = "enabled", så pushar till master på GitHub befordrades till produktionsdomänerna trots att repots policy förväntar sig att produktionsspeglarna bara levererar release-artefakter.
  • Konsekvens: Märkena för verifierade speglar i appkatalogen kan bli felaktiga, eftersom produktionsdomänerna levererar den senaste utvecklingscommiten i stället för den GitHub-release-ZIP vars index.html-hash är registrerad i about/src/lib/apps-data.ts.
  • Åtgärd: Innan du lägger till eller uppdaterar metadata för spegelverifiering, kontrollera Vercel-projektet med vercel api /v9/projects/<project-id> och bekräfta att gitProviderOptions.createDeployments = "disabled". Distribuera innehållet i release-ZIP:en med vercel deploy --prebuilt --prod och använd seedit-omega.vercel.app eller 5chan-omega.vercel.app för utvecklingsdistributioner.
  • Status: confirmed

Portless 0.11 återanvänder gammalt proxytillstånd om inte startskriptet tvingar fram HTTPS​

  • Datum: 2026-04-28
  • Observerad av: Tommaso + Codex
  • Sammanhang: Uppgradering av det vanliga yarn start-flödet från den gamla proxy-URL:en http://bitsocial.localhost:1355 till https://bitsocial.localhost.
  • Det överraskande: Även med portless@0.11.1 installerat återanvände Portless den befintliga HTTP-proxyn ~/.portless/proxy.port = 1355 och skrev ut den gamla :1355-adressen.
  • Konsekvens: Det räcker inte att uppdatera paketversioner och dokumentation. yarn start kan fortfarande annonsera och använda den gamla adressen när en bidragsgivare har gammalt Portless-tillstånd igång.
  • Åtgärd: Låt startskripten uttryckligen starta Portless HTTPS-proxy på port 443 innan appruttarna registreras, så att körningsflödet migrerar bort från det sparade 1355-tillståndet i stället för att ärva det.
  • Status: confirmed

Portless ändrar den kanoniska lokala app-adressen​

  • Datum: 2026-03-18
  • Observerad av: Codex
  • Sammanhang: Webbläsarverifiering och röktestflöden
  • Det överraskande: Standardadressen lokalt är inte den vanliga Vite-porten. Repot förväntar sig https://bitsocial.localhost via Portless, så att kontrollera localhost:3000 eller localhost:5173 kan träffa fel app eller ingenting alls.
  • Konsekvens: Webbläsarkontroller kan misslyckas eller validera fel mål, även när utvecklingsservern mår bra.
  • Åtgärd: Använd https://bitsocial.localhost först. Kringgå den bara med PORTLESS=0 corepack yarn start när du uttryckligen behöver en direkt Vite-port.
  • Status: confirmed

Commitizen-hooks blockerar icke-interaktiva commits​

  • Datum: 2026-03-18
  • Observerad av: Codex
  • Sammanhang: Agentdrivna commit-arbetsflöden
  • Det överraskande: git commit utlöser Commitizen via Husky och väntar på interaktiv TTY-inmatning, vilket får icke-interaktiva agentskal att hänga sig.
  • Konsekvens: Agenter kan fastna på obestämd tid under vad som borde vara en helt vanlig commit.
  • Åtgärd: Använd git commit --no-verify -m "message" för commits som agenter skapar. Människor kan fortfarande använda corepack yarn commit eller corepack yarn exec cz.
  • Status: confirmed

Corepack krävs för att undvika Yarn classic​

  • Datum: 2026-03-19
  • Observerad av: Codex
  • Sammanhang: Bytet av pakethanterare till Yarn 4
  • Det överraskande: Maskinen har fortfarande en global installation av Yarn classic i PATH, så att köra enbart yarn kan leda till v1 i stället för den fastlåsta Yarn 4-versionen.
  • Konsekvens: Utvecklare kan av misstag kringgå repots låsning av pakethanterare och få ett annat installationsbeteende eller en annan låsfil.
  • Åtgärd: Använd corepack yarn ... för skalkommandon, eller kör corepack enable först så att enbart yarn leder till den fastlåsta Yarn 4-versionen.
  • Status: confirmed

Fasta Portless-appnamn krockar mellan Bitsocial Web-worktrees​

  • Datum: 2026-03-30
  • Observerad av: Codex
  • Sammanhang: Att köra yarn start i en Bitsocial Web-worktree medan en annan worktree redan levererade via Portless
  • Det överraskande: Att använda det bokstavliga Portless-appnamnet bitsocial i varje worktree gör att själva rutten krockar, även när portarna bakom skiljer sig åt, så den andra processen misslyckas eftersom bitsocial.localhost redan är registrerad.
  • Konsekvens: Parallella Bitsocial Web-grenar kan blockera varandra, trots att Portless är tänkt att låta dem samexistera utan problem.
  • Åtgärd: Låt Portless-starten gå via scripts/start-dev.mjs, som numera använder en grenbaserad *.bitsocial.localhost-rutt utanför det kanoniska fallet och faller tillbaka på en grenbaserad rutt när det rena namnet bitsocial.localhost redan är upptaget.
  • Status: confirmed

Förhandsvisningen av dokumentationen brukade hårdkoda port 3001​

  • Datum: 2026-03-30
  • Observerad av: Codex
  • Sammanhang: Att köra yarn start parallellt med andra lokala repon och agenter
  • Det överraskande: Rotens utvecklingskommando körde dokumentationsarbetsytan med docusaurus start --port 3001, så hela utvecklingssessionen föll så fort en annan process redan ägde 3001, trots att huvudappen redan använde Portless.
  • Konsekvens: yarn start kunde döda webbprocessen direkt efter start och avbryta orelaterat lokalt arbete på grund av en portkrock för dokumentationen.
  • Åtgärd: Låt dokumentationsstarten gå via yarn start:docs, som numera använder Portless plus scripts/start-docs.mjs för att respektera en inmatad ledig port eller falla tillbaka på nästa lediga port när det körs direkt.
  • Status: confirmed

Det fasta Portless-värdnamnet för dokumentationen var hårdkodat​

  • Datum: 2026-04-03
  • Observerad av: Codex
  • Sammanhang: Att köra yarn start i en sekundär Bitsocial Web-worktree medan en annan worktree redan levererade dokumentationen via Portless
  • Det överraskande: start:docs registrerade fortfarande det bokstavliga värdnamnet docs.bitsocial.localhost, så yarn start kunde misslyckas trots att about-appen redan visste hur den skulle undvika Portless-ruttkrockar för sitt eget värdnamn.
  • Konsekvens: Parallella worktrees kunde inte använda rotens utvecklingskommando på ett tillförlitligt sätt, eftersom dokumentationsprocessen avslutades först och concurrently sedan dödade resten av sessionen.
  • Åtgärd: Låt dokumentationsstarten gå via scripts/start-docs.mjs, som numera härleder samma grenbaserade Portless-värdnamn som about-appen och matar in den delade publika adressen som mål för utvecklingsproxyn på /docs.
  • Status: confirmed

Worktree-skal kan missa repots fastlåsta Node-version​

  • Datum: 2026-04-03
  • Observerad av: Codex
  • Sammanhang: Att köra yarn start i Git-worktrees som .claude/worktrees/* eller angränsande worktree-utcheckningar
  • Det överraskande: Vissa worktree-skal löste upp node och yarn node till Homebrew-Node 25.2.1, trots att repot låser 22.12.0 i .nvmrc, så yarn start kunde tyst köra utvecklingsstartarna på fel körtid.
  • Konsekvens: Utvecklingsserverns beteende kan glida isär mellan huvudutcheckningen och worktrees, vilket gör buggar svåra att återskapa och bryter mot repots förväntade Node 22-verktygskedja.
  • Åtgärd: Låt utvecklingsstartarna gå via scripts/start-dev.mjs och scripts/start-docs.mjs, som numera startar om sig själva under Node-binären från .nvmrc när det aktuella skalet har fel version. Skalkonfigurationen bör ändå föredra nvm use.
  • Status: confirmed

Rester av docs-site/ kan dölja saknad dokumentationskälla efter refaktoreringen​

  • Datum: 2026-04-01
  • Observerad av: Codex
  • Sammanhang: Städning av monorepot efter sammanslagningen, när Docusaurus-projektet flyttades från docs-site/ till docs/
  • Det överraskande: Den gamla mappen docs-site/ kan ligga kvar på disken med inaktuella men viktiga filer som i18n/, även efter att det spårade repot flyttat till docs/. Det får refaktoreringen att se dubblerad ut lokalt och kan dölja att spårade dokumentationsöversättningar aldrig faktiskt flyttades in i docs/.
  • Konsekvens: Agenter kan radera den gamla mappen som ”skräp” och av misstag förlora den enda lokala kopian av dokumentationsöversättningarna, eller fortsätta redigera skript som fortfarande pekar på den döda docs-site/-sökvägen.
  • Åtgärd: Behandla docs/ som det enda kanoniska dokumentationsprojektet. Innan du raderar lokala rester av docs-site/, återställ spårad källkod som docs/i18n/ och uppdatera skript och hooks så att de slutar referera till docs-site.
  • Status: confirmed

Flerspråkig förhandsvisning av dokumentationen kan få minnesanvändningen att skjuta i höjden under verifiering​

  • Datum: 2026-04-01
  • Observerad av: Codex
  • Sammanhang: Att åtgärda i18n, lokalruttning och Pagefind-beteende i dokumentationen med yarn start:docs plus Playwright
  • Det överraskande: Standardläget för dokumentationsförhandsvisningen gör numera ett fullständigt flerspråkigt dokumentationsbygge plus Pagefind-indexering innan den börjar leverera, och att hålla den processen vid liv jämsides med flera Playwright- eller Chrome-sessioner kan sluka betydligt mer minne än en vanlig Vite-loop eller en Docusaurus-utvecklingsloop med en enda lokal.
  • Konsekvens: Maskinen kan bli minnesbegränsad, webbläsarsessioner kan krascha, och avbrutna körningar kan lämna kvar inaktuella dokumentationsservrar eller huvudlösa webbläsare som fortsätter äta minne.
  • Åtgärd: För dokumentationsarbete som inte kräver verifiering av lokalruttning eller Pagefind, föredra DOCS_START_MODE=live yarn start:docs. Använd bara standardläget med flerspråkig förhandsvisning när du behöver validera översatta rutter eller Pagefind. Håll en enda Playwright-session, stäng gamla webbläsarsessioner innan du öppnar nya, och stoppa dokumentationsservern efter verifieringen om du inte längre behöver den.
  • Status: confirmed

translate-docs.py kan lämna dokumentationslokaler halvöversatta eller med trasiga länkmål​

  • Datum: 2026-04-06
  • Observerad av: Codex
  • Sammanhang: Att åtgärda lokaliserade dokumentationsrutter och innehåll efter att yarn start:docs levererade engelska detaljsidor eller inte lyckades bygga lokalutdata
  • Det överraskande: Översättningskedjan för dokumentationen hade två repospecifika felfall samtidigt: scripts/translate-docs.py extraherade bara en liten delmängd av DocsHome-meddelandena när tr(...)-anropen använde former som skriptet inte kunde tolka, och översatt markdown under docs/i18n/** kunde innehålla maskinöversatta sluggar eller ZXQPLACEHOLDER-artefakter inuti länkmål.
  • Konsekvens: Lokaliserade startsidor kan tyst falla tillbaka på engelska, lokaliserade detaljsidor kan se oöversatta ut, och ett fullständigt yarn docs:build kan misslyckas på trasiga lokallänkar trots att källdokumentationen är korrekt.
  • Åtgärd: Efter att du ändrat dokumentationsöversättningar eller genererat om lokalfiler ska du alltid köra yarn docs:build från repots rot, söka igenom markdown under docs/i18n/** efter ZXQPLACEHOLDER, och kontrollera att översatta länkar fortfarande pekar på kanoniska dokumentsluggar som /apps/5chan/ i stället för översatta URL-sökvägar. Om texten i DocsHome har ändrats, bekräfta att scripts/translate-docs.py fortfarande extraherar alla docs.home.*-meddelanden.
  • Status: confirmed

No-JS-kontroller för about-sajten måste använda Portless-rutten, inte en fristående SSR-förhandsvisning​

  • Datum: 2026-04-12
  • Observerad av: Codex
  • Sammanhang: Verifiering av stöd för avstängd JavaScript på about/-sajten från en grenworktree
  • Det överraskande: En fristående SSR-förhandsvisning kan se helt frisk ut medan den faktiska grenbaserade Portless-rutten fortfarande levererar fel appskal eller en äldre process. I det här repot är det verkliga lokala kontraktet Portless-värdnamnet från yarn start, inte en tillfällig förhandsvisningsserver.
  • Konsekvens: Agenter kan felaktigt hävda att stödet för avstängd JavaScript fungerar, eller missa regressioner som bara syns på *.bitsocial.localhost.
  • Åtgärd: För webbläsarverifiering av about/ ska du alltid starta den riktiga lokala servern med yarn start eller yarn start:about och testa den grenbaserade Portless-adressen först. Om ett Portless-värdnamn ser inaktuellt ut, undersök och stoppa den gamla processen innan du testar igen.
  • Status: confirmed

chain/ var osynlig för yarn build:verify och yarn doctor​

  • Datum: 2026-07-05
  • Observerad av: Codex
  • Sammanhang: Verifiering av en diff som bara rörde chain/ efter att arbetsytan chain/ (fristående Vite-app för chain.bitsocial.net) lagts till i monorepot.
  • Det överraskande: scripts/verify-build.mjs kände bara igen sökvägsprefixen about/, docs/ och stats/, så en diff som bara rörde chain/ skrev ut "No targeted build checks matched the current diff" och körde inget bygge alls, trots att build:chain redan fanns i rotens package.json. Dessutom var yarn doctor hårdkodat till react-doctor about -y, så React-ändringar under chain/src fick noll täckning av React Doctor.
  • Konsekvens: Agenter som verifierade chain-ändringar behövde veta att de skulle anropa yarn build:chain direkt i stället för att lita på yarn build:verify, och React-problem i chain/src (effekter, hooks, död kod) upptäcktes aldrig av yarn doctor.
  • Åtgärd: scripts/verify-build.mjs har numera en chain/-gren som speglar about/-grenen, och doctor samt doctor:verbose kör nu react-doctor --project about,chain -y i ett enda anrop. doctor:score gäller fortfarande bara about, eftersom --score tyst skriver ut ingenting när det kombineras med --project för fler än ett projekt; använd yarn react-doctor --project about,chain --verbose -y (eller --json) om du behöver en poäng för chain.
  • Status: confirmed

Webbläsarens P2P körs på säkra WebSockets; pkc-js nekar WebRTC och WebTransport som standard​

  • Datum: 2026-08-02
  • Observerad av: Claude
  • Sammanhang: Att skriva text för landningssidan och dokumentationen om hur Bitsocials peer-to-peer i webbläsaren fungerar
  • Det överraskande: @pkcprotocol/pkc-js levereras med en standardgrind för anslutningar som avvisar WebRTC- och WebTransport-uppkopplingar i webbläsaren — dist/browser/helia/dial-transport-filter.js exporterar DENIED_DIAL_TRANSPORTS_BY_DEFAULT = ["webrtc", "webrtc-direct", "webtransport"]. Kommentaren i källkoden anger skälet: i webbläsaren lägger de transporterna till långa och ofta misslyckade vägar för att upprätta anslutningar (STUN/ICE, rotation av certhash) som gör sidladdningen långsammare, medan WebSocket är direkt och tillförlitlig. Varje aktiv peer i bloggens P2P-statuspanel visar "Secure WebSocket". Grinden ligger i node_modules, så inget i repot antyder att den finns.
  • Konsekvens: Det är mycket lätt att skriva teknisk text som låter rimlig men är falsk — till exempel att ge WebTransport, som nådde Baseline i webbläsare i mars 2026, äran för att Bitsocials peer-to-peer i webbläsaren är möjligt. Det påståendet hann gå ut på landningssidan, i jämförelsetabellen och på två dokumentationssidor innan utvecklaren upptäckte det. Felaktiga arkitekturpåståenden på publika sidor granskas av precis den utvecklarpublik som sajten riktar sig till.
  • Åtgärd: Härled aldrig vilka transporter Bitsocial använder från vad libp2p eller webbläsarplattformen stöder i princip. Kontrollera den aktuella nekandelistan i node_modules/@pkcprotocol/pkc-js/dist/browser/helia/dial-transport-filter.js, bekräfta att ingen connectionGater-överstyrning finns under about/src/, och läs de faktiska transportetiketterna i bloggens panel "P2P status" innan du gör något publikt påstående. Uppströmsändringen som faktiskt gjorde publicering från webbläsaren möjlig var korrigeringen av monoton seqno i @libp2p/gossipsub 15.0.21 (maj 2026); pkc-js levererar för närvarande 16.0.4.
  • Status: confirmed

Relativa ./page.md-länkar från en oöversatt dokumentationssida bryter varje lokaliserat bygge​

  • Datum: 2026-08-02
  • Observerad av: Claude
  • Sammanhang: Att lägga till en ny sida som bara fanns på engelska, docs/browser-p2p.md, som länkade till befintlig dokumentation med ./peer-to-peer-protocol.md och ./apps/5chan.md
  • Det överraskande: Varje lokal under docs/i18n/<lang>/docusaurus-plugin-content-docs/current/ speglar dokumentationsträdet. En ny sida som saknas i de speglarna renderas ändå i varje lokal via engelsk reserv, men dess relativa markdown-länkar går inte längre att lösa upp — Docusaurus genererar /ar/browser-p2p/peer-to-peer-protocol.md/ och avbryter bygget med "Docusaurus found broken links!". Det avgörande är att yarn build:verify och yarn docs:build:verify bara bygger en och går igenom utan anmärkning; bara ett fullständigt yarn docs:build avslöjar problemet, och det avbryts på den första lokalen i bokstavsordning (ar).
  • Konsekvens: En dokumentationsändring kan klara varje snabb lokal kontroll och ändå bryta det flerspråkiga produktionsbygget. Felet ser dessutom orelaterat ut till ändringen, eftersom felmeddelandet pekar ut en lokalsökväg som författaren aldrig rörde.
  • Åtgärd: Använd rotrelativa länkar (/peer-to-peer-protocol/, /apps/5chan/) i stället för relativa .md-länkar på varje dokumentationssida som inte speglas in i docs/i18n/**; Docusaurus lägger till lokalprefixet automatiskt. docs/build-your-own-client.md är det befintliga exemplet. Kör ett fullständigt yarn docs:build — inte bara build:verify — innan du lämnar över en ändring som lägger till eller länkar till en dokumentationssida.
  • Status: confirmed

update-translations.js måste köras från about/, och samtidiga körningar tappar nycklar tyst​

  • Datum: 2026-08-02
  • Observerad av: Claude
  • Sammanhang: Att applicera 26 översatta i18next-nycklar över alla 36 lokaler via skillen translate
  • Det överraskande: Två separata fällor i samma skript. För det första löser scripts/update-translations.js upp sitt mål som path.join(process.cwd(), "public", "translations"), men det här repot håller översättningarna i about/public/translations. Att köra det dokumenterade kommandot från repots rot misslyckas varje gång med "Translations directory not found" — docs/agent-playbooks/translations.md visar node scripts/update-translations.js ..., vilket läses som ett kommando från repots rot. För det andra är varje körning en läs-ändra-skriv över alla 36 lokalfiler, så två körningar samtidigt skriver över varandra och en nyckel försvinner utan felmeddelande. Skillen translate instruerar uttryckligen att upp till 4 underagenter ska startas samtidigt, och var och en av dem skulle anropa skriptet.
  • Konsekvens: Formen från repots rot misslyckas högljutt och slösar bort en hel omgång. Samtidighetsproblemet misslyckas tyst: nycklar försvinner från godtyckliga lokaler, och diffen ser fortfarande rimlig ut.
  • Åtgärd: Kör det som cd about && node ../scripts/update-translations.js --key <key> --map <abs-path> --write. Låt aldrig översättande underagenter skriva lokalfiler samtidigt — låt dem bara producera JSON-ordböcker, och applicera sedan varje nyckel seriellt från föräldraagenten. Verifiera programmatiskt efter appliceringen att varje nyckel finns i alla 35 icke-engelska lokaler och att inget värde är byte-identiskt med den engelska källan.
  • Status: confirmed