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
seeditoch5chanhadegitProviderOptions.createDeployments = "enabled", så pushar tillmasterpå 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 iabout/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 attgitProviderOptions.createDeployments = "disabled". Distribuera innehållet i release-ZIP:en medvercel deploy --prebuilt --prodoch användseedit-omega.vercel.appeller5chan-omega.vercel.appfö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:enhttp://bitsocial.localhost:1355tillhttps://bitsocial.localhost. - Det överraskande: Även med
portless@0.11.1installerat återanvände Portless den befintliga HTTP-proxyn~/.portless/proxy.port = 1355och skrev ut den gamla:1355-adressen. - Konsekvens: Det räcker inte att uppdatera paketversioner och dokumentation.
yarn startkan 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
443innan appruttarna registreras, så att körningsflödet migrerar bort från det sparade1355-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.localhostvia Portless, så att kontrolleralocalhost:3000ellerlocalhost:5173kan 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.localhostförst. Kringgå den bara medPORTLESS=0 corepack yarn startnä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 commitutlö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ändacorepack yarn commitellercorepack 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 enbartyarnkan 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örcorepack enableförst så att enbartyarnleder 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 starti en Bitsocial Web-worktree medan en annan worktree redan levererade via Portless - Det överraskande: Att använda det bokstavliga Portless-appnamnet
bitsociali varje worktree gör att själva rutten krockar, även när portarna bakom skiljer sig åt, så den andra processen misslyckas eftersombitsocial.localhostredan ä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 namnetbitsocial.localhostredan ä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 startparallellt 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 ägde3001, trots att huvudappen redan använde Portless. - Konsekvens:
yarn startkunde 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 plusscripts/start-docs.mjsfö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 starti en sekundär Bitsocial Web-worktree medan en annan worktree redan levererade dokumentationen via Portless - Det överraskande:
start:docsregistrerade fortfarande det bokstavliga värdnamnetdocs.bitsocial.localhost, såyarn startkunde 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
concurrentlysedan 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 starti Git-worktrees som.claude/worktrees/*eller angränsande worktree-utcheckningar - Det överraskande: Vissa worktree-skal löste upp
nodeochyarn nodetill Homebrew-Node25.2.1, trots att repot låser22.12.0i.nvmrc, såyarn startkunde 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.mjsochscripts/start-docs.mjs, som numera startar om sig själva under Node-binären från.nvmrcnär det aktuella skalet har fel version. Skalkonfigurationen bör ändå föredranvm 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/tilldocs/ - Det överraskande: Den gamla mappen
docs-site/kan ligga kvar på disken med inaktuella men viktiga filer somi18n/, även efter att det spårade repot flyttat tilldocs/. Det får refaktoreringen att se dubblerad ut lokalt och kan dölja att spårade dokumentationsöversättningar aldrig faktiskt flyttades in idocs/. - 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 avdocs-site/, återställ spårad källkod somdocs/i18n/och uppdatera skript och hooks så att de slutar referera tilldocs-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:docsplus 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:docslevererade engelska detaljsidor eller inte lyckades bygga lokalutdata - Det överraskande: Översättningskedjan för dokumentationen hade två repospecifika felfall samtidigt:
scripts/translate-docs.pyextraherade bara en liten delmängd avDocsHome-meddelandena närtr(...)-anropen använde former som skriptet inte kunde tolka, och översatt markdown underdocs/i18n/**kunde innehålla maskinöversatta sluggar ellerZXQPLACEHOLDER-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:buildkan 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:buildfrån repots rot, söka igenom markdown underdocs/i18n/**efterZXQPLACEHOLDER, 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 iDocsHomehar ändrats, bekräfta attscripts/translate-docs.pyfortfarande extraherar alladocs.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 medyarn startelleryarn start:aboutoch 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örchain.bitsocial.net) lagts till i monorepot. - Det överraskande:
scripts/verify-build.mjskände bara igen sökvägsprefixenabout/,docs/ochstats/, 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 attbuild:chainredan fanns i rotenspackage.json. Dessutom varyarn doctorhårdkodat tillreact-doctor about -y, så React-ändringar underchain/srcfick noll täckning av React Doctor. - Konsekvens: Agenter som verifierade chain-ändringar behövde veta att de skulle anropa
yarn build:chaindirekt i stället för att lita påyarn build:verify, och React-problem ichain/src(effekter, hooks, död kod) upptäcktes aldrig avyarn doctor. - Åtgärd:
scripts/verify-build.mjshar numera enchain/-gren som speglarabout/-grenen, ochdoctorsamtdoctor:verbosekör nureact-doctor --project about,chain -yi ett enda anrop.doctor:scoregäller fortfarande baraabout, eftersom--scoretyst skriver ut ingenting när det kombineras med--projectför fler än ett projekt; användyarn 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-jslevereras med en standardgrind för anslutningar som avvisar WebRTC- och WebTransport-uppkopplingar i webbläsaren —dist/browser/helia/dial-transport-filter.jsexporterarDENIED_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 inode_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 ingenconnectionGater-överstyrning finns underabout/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/gossipsub15.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.mdoch./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 attyarn build:verifyochyarn docs:build:verifybara byggerenoch går igenom utan anmärkning; bara ett fullständigtyarn docs:buildavslö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 idocs/i18n/**; Docusaurus lägger till lokalprefixet automatiskt.docs/build-your-own-client.mdär det befintliga exemplet. Kör ett fullständigtyarn docs:build— inte barabuild:verify— innan du lämnar över en ändring som lägger till eller länkar till en dokumentationssida. - Status: confirmed
Samtidiga körningar av update-translations.js 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: Varje körning är 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
translateinstruerar uttryckligen att upp till 4 underagenter ska startas samtidigt, och var och en av dem skulle anropa skriptet. - Konsekvens: Det misslyckas tyst: nycklar försvinner från godtyckliga lokaler, och diffen ser fortfarande rimlig ut.
- Åtgärd: 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
- Uppdatering (2026-08-10): Skriptet löste tidigare också upp sitt mål som
path.join(process.cwd(), "public", "translations"), så det dokumenterade kommandot från repots rot misslyckades med "Translations directory not found" och måste köras frånabout/. Nu löser det upp arbetsytan från den aktuella katalogen eller från sin egen plats, och fungerar varifrån som helst. Samtidighetsfällan ovan är oförändrad.
Annoteringskontroller i utvecklingsläge kan fånga upp automatiserade klick
- Sammanhang: About- och chain-sajterna har fasta kontroller i nedre högra hörnet, där även Agentation-verktygsfältet visas under utveckling.
- Åtgärd:
scripts/pw-session.sh openregistrerarwindow.__NO_DEV_TOOLBAR__ = trueinnan sidan laddas om. Agentations initierare respekterar också__VISUAL_TESTING__och__PROFILING__; källkodsinspektion förblir tillgänglig oberoende av detta. Direkt webbläsarautomatisering måste sätta samma flagga innan applikationen laddas.
skills add installerar Codex- och Cursor-kopior i den gitignorerade katalogen .agents/
- Datum: 2026-08-18
- Observerad av: Tommaso + Claude
- Sammanhang: Att installera skillen
improve-threejsfrånmillionco/react-doctormedskills-CLI:t (vercel-labs/skills). - Det överraskande:
npx skills add <repo> --skill <name> --agent codexoch--agent cursorskriver båda till.agents/skills/<name>/, inte till.codex/skills/eller.cursor/skills/.AGENTS.mdförbjuder en.agents/-katalog på reponivå och.gitignore:29ignorerar den, så båda kopiorna blir tyst ospårade. Bara--agent claude-codeskriver till den förväntade.claude/skills/. Dessutom misslyckas den dokumenterade kommaseparerade formen (--agent claude-code,codex,cursor) med "Invalid agents" och installerar ingenting, trots att varje namn är giltigt för sig. - Konsekvens: Installationen rapporterar att den lyckades medan två av de tre verktygskedjornas kopior hamnar någonstans där de aldrig kommer att checkas in, så Codex och Cursor saknar tyst skillen efter en ny klon. Kommaformen kan också ge en installation som inte gör något men ser ut att ha lyckats.
- Aktuell åtgärd: Repot spårar nu
.agents/skillssom sin kanoniska källa och genererar Claude-kopior medyarn ai-workflow:sync. Det tidigare förbudet mot.agentsoch ignoreringsregeln har tagits bort. Kopiera inte nya skills till tre oberoende rötter; kontrollera den genererade pariteten och appens katalog efter att du har lagt till en skill. - Status: confirmed