Ett repo. Alla delar.

Börja med ett eget repo

Öppna startmallen på GitHub och välj Use this template → Create a new repository. Skapa ett publikt repo på ditt personliga GitHub-konto. Klona sedan ditt nya repo till datorn. Att bara klona vår mall ger dig inget eget repo att registrera.

Använd ett repo per år. Du får en gemensam presentation på förstasidan med en repolänk för varje år; deltagarlistan visar 12 personer per sida. Mallen börjar med 2025 så att du kan prova direkt. Gå också med i vår privata AoC-grupp enligt checklistan.

Från push till topplista

Du fyller i advent.json och pushar. Använd repots default branch, vanligtvis main. Första pushen kan vara utan färdiga lösningar.
GitHub startar .github/workflows/advent.yml. Workflowet kör Python-skriptet .github/scripts/publish.py.
Skriptet kontaktar vårt API. Det skickar vilka dagar, delar och spår du har ändrat. GitHub intygar vilket repo, konto och vilken commit som skickar uppgifterna.
API:t registrerar repot. Vi läser namn, valfri presentation, AoC-ID och år från advent.json i just den committen. Du behöver inte ange GitHub-konto eller repolänk separat. Din presentation och repolänk visas på förstasidan direkt, med upp till en minuts cache.
Vi kontrollerar AoC-listan. Nästa schemalagda hämtning kontrollerar att ditt angivna AoC-ID finns i gruppen för rätt år. Normalt tar det upp till 15 minuter. Därefter syns ditt namn och repo på våra topplistor.
Godkänt svar öppnar för analys. När AoC har godkänt rätt dag och del läser vi koden i den registrerade committen. Vi räknar kodrader, identifierar språk och läser eventuell modellrapport. Analysen kör inte ditt program.

Resultatet sparas i vår databas och visas på topplistorna. En förbättring med en ny commit ger en ny version. Samma commit ger inga dubbletter.

Vi litar på att du anger ditt eget AoC-ID. GitHub bekräftar repo och ägare; AoC-listan bekräftar medlemskap, inte vem som äger AoC-kontot. Ingen engångskod eller ändring av ditt AoC-visningsnamn behövs.

Filerna i repots rot

Fil	Vad den gör och vad du ändrar
`advent.json`	Kopplar repot till rätt år och AoC-ID. Fyll i den först. Fälten beskrivs nedan.
`README.md`	Repots startsida. Beskriv dina lösningar, hur de körs och vad du har lärt dig. Länka till dagarna och ditt eventuella agentsystem.
`.gitignore`	Hindrar bland annat `.private/`, `.env`, loggar och byggfiler från att läggas till i Git. Behåll skyddet och komplettera för ditt språk. Redan incheckade filer tas inte bort av en ignore-regel.
`.dockerignore`	Håller bland annat `.private/`, `.env` och Git-historiken utanför Dockers byggkontext. Behåll skyddet så att privata filer inte följer med vid bygge.
`.env.example`	Visar platsen för en lokal `AOC_SESSION` om ditt eget agentsystem behöver den. Kopiera vid behov till `.env` på din dator. Inga riktiga hemligheter ska ligga i exempelfilen. Vårt API behöver ingen deltagarnyckel.

Det här fyller du i i advent.json

{
  "schema_version": 1,
  "year": 2025,
  "aoc_user_id": "DITT_AOC_ID",
  "display_name": "Ditt namn",
  "bio": "Nyfiken på Rust och små agenter."
}

schema_version: behåll 1. Det anger filformatet.
year: uppgiftsåret för repot, exempelvis 2025 för övning.
aoc_user_id: logga in på AoC och öppna Settings. Leta efter namnalternativet Anonymous User #123456. Siffrorna efter # är ditt numeriska ID. Du behöver inte välja alternativet eller ändra ditt namn. Skriv numret som en sträng mellan citattecken. Det är inte ditt username, visningsnamn eller gruppens anslutningskod.
display_name: namnet du vill visa på vår sajt. Det behöver inte matcha namnet på AoC.
bio: valfri presentation på högst 160 tecken. Berätta vem du är eller vad du vill lära dig. Ändra eller töm fältet med en ny push.

Committa filen och pusha till din default branch. Öppna sedan GitHub → ditt repo → Actions → Publicera Advent-lösningar → senaste körningen. Läs sammanfattningen för besked om registreringen. Ett tomt AoC-ID gör att workflowet avslutas utan att skicka något.

Filerna som sköter publiceringen

Fil	Vad den gör och vad du ändrar
`.github/workflows/advent.yml`	Startar publiceringen vid push till repots default branch. Kan också startas med Run workflow. Ger skriptet rätt att läsa repot och begära ett kortlivat GitHub-intyg. Låt filen ligga kvar på den här sökvägen. Du behöver normalt inte ändra den.
`.github/scripts/publish.py`	Hittar ändrade dagslösningar, begär GitHub-intyget och skickar metadata till vårt API. Visar svaret i körningens sammanfattning. Skriptet skickar inga inputfiler eller modellnycklar. Du behöver normalt inte ändra det.
`.github/workflows/examples.yml`	Bygger och testar de två medföljande Docker-exemplen och kontrollerar båda delarnas svar med egna testdata. Det gäller exemplen. Lägg till egna CI-steg om du vill köra tester för dina `days/`-lösningar i GitHub Actions.

Anropet går till https://aoc.artofcode.se/api/v1/github/push. För särskild testning kan repository variable ADVENT_API_URL peka på testmiljön. Vanliga deltagare ska behålla standardadressen.

Din dagslösning, fil för fil

Mallen har två startmappar: days/01/manual/ för eget hantverk och days/01/agent/ för agentens lösning. Filerna nedan gäller båda mapparna. För dag 2 skapar du motsvarande struktur under days/02/.

Fil eller plats	Vad den gör och vad du ändrar
`solution.json`	Finns i båda startmapparna. Ange språk, vilka delar lösningen stöder och eventuell egen delad kod. `choose-your-language` betyder att lösningen inte är redo att registreras.
`README.md`	Finns i båda startmapparna. Fyll i huvudidén, installation, bygg- och körkommandon, tester och hur någon annan kan bygga vidare.
`src/.gitkeep`	Håller den tomma källkodsmappen i Git. Lägg din riktiga kod här, exempelvis `src/solve.py` eller `src/main.rs`. `.gitkeep` kan tas bort när mappen innehåller kod.
`tests/.gitkeep`	Håller testmappen i Git. Lägg egna testfiler här, med små data som du själv skapar. Publicera inte AoC-indata.
`Dockerfile`	Skapar du själv per dag och spår. Beskriver hur lösningen byggs och körs. Den finns färdig i undervisningsexemplen, inte i de tomma dagsmapparna.
`run.json`	Valfri fil som du eller agenten skapar i agentens dagsmapp. Beskriver faktiskt använda verktyg och modeller. Formatet finns i `runs/README.md`. Behövs inte för hantverksspåret.

Exempel på en färdig solution.json:

{
  "schema_version": 1,
  "language": "Python",
  "parts": [1, 2],
  "shared_paths": ["shared/manual"]
}

Ange bara delar som programmet stöder. Använd "shared_paths": [] om lösningen inte använder egen delad kod. Språklistan bygger på källfilernas filändelser; språkfältet i manifestet är din egen beskrivning.

Samma sätt att köra varje dag

Bygg från repots rot. Lösningen tar --part 1 eller --part 2, läser stdin och skriver svaret på stdout. Diagnostik går till stderr.

docker build -f days/01/manual/Dockerfile -t advent-day01 .
docker run --rm -i advent-day01 --part 1 < .private/inputs/2025-01.txt

Docker gör det enkelt för andra att prova koden. Privata indata skickas in vid körning och ska inte ligga i imagen. Vår server gör statisk analys och mäter ingen exekveringstid. I agentens dagsmapp kör Docker den producerade lösningen; själva agentsystemet ligger separat.

Agent, delad kod och rapporter

Fil eller plats	Vad den gör och vad du ändrar
`agent/README.md`	Fyll i hur du installerar, startar, testar och vidareutvecklar ditt agentsystem. Ange verktyg, modellval och vilka steg som kräver din hjälp.
`agent/src/.gitkeep`	Plats för din agents kod: exempelvis hämtning, modelladapter, testkörning och publicering. Mallen innehåller inget färdigt agentsystem.
`agent/instructions/.gitkeep`	Plats för dina agentinstruktioner. Skapa exempelvis `solve.md` och förklara i agentens README hur instruktionerna används.
`shared/manual/.gitkeep`	Plats för egen kod som flera hantverkslösningar använder. Ange sökvägen i berörda `solution.json` så att kodraderna räknas.
`shared/agent/.gitkeep`	Motsvarande plats för egen kod som flera agentlösningar använder. Ange sökvägen i berörda manifest.
`runs/README.md`	Dokumenterar modellrapportens format. Själva rapporten ska ligga vid lösningen, exempelvis `days/01/agent/run.json`, så att vi kan läsa den vid samma commit.

Du väljer agentverktyg själv. Startmallen startar ingen AI-tjänst automatiskt. Modelluppgifter är självrapporterade; lämna okända värden tomma enligt rapportformatet.

De färdiga exemplen

Under examples/2025/day01/manual/ och examples/2025/day01/agent/ finns två AI-assisterade undervisningsexempel. De innehåller spoilers. De ligger utanför days/ och registreras inte som dina egna lösningar.

Följande filer finns i båda exempelmapparna:

Fil	Innehåll
`README.md`	Förklarar lösningen, varje Dockerfile-steg, egna provdata, körkommandon och lokal tidtagning.
`solution.json`	Visar ett ifyllt manifest för Python och båda delarna.
`Dockerfile`	Paketerar Python, kod och tester. Kör testerna under bygget och startar sedan lösningen utan root-behörighet.
`src/solve.py`	Lösningsprogrammet. Läser stdin och tar vald del via kommandoraden.
`tests/test_solve.py`	Tester med egna små data och en oberoende simulering att jämföra mot.

Agentexemplet har dessutom:

Fil	Innehåll
`examples/2025/day01/agent/instructions/solve.md`	Instruktioner som du kan ge till ditt agentverktyg för ett eget försök.
`examples/2025/day01/agent/run.json`	Visar rapportformatet. Modellistan är tom eftersom exakt modell-ID inte har verifierats för undervisningsexemplet.

Det här stannar på datorn

.private/ och .env skapar du lokalt vid behov. De finns inte med som privata filer i mallen. Spara egna AoC-indata under exempelvis .private/inputs/2025-01.txt och hemligheter i .env eller ditt verktygs säkra inställningar. Du ansvarar för att ditt eget verktyg läser rätt lokala inställningar; exempelfilen laddas inte automatiskt.

Varken GitHub-repot, Docker-imagen eller vår tjänst ska få dina personliga indata, sessionscookies, modellnycklar eller råa agentkonversationer.

Om något inte dyker upp

Ingen Actions-körning: kontrollera att .github/workflows/advent.yml finns kvar, att GitHub Actions är aktiverat i repot och att du pushat till default branch.
Körningen ber om AoC-ID: fyll i advent.json, committa och pusha igen.
Registrerat, men inget namn på förstasidan: vänta upp till en minut på sidans cache och ladda om. Kontrollera att senaste Actions-körningen säger att registreringen tagits emot.
Namnet syns, men inga AoC-resultat: kontrollera AoC-ID, år och gruppmedlemskap. Vänta på nästa AoC-hämtning, normalt upp till 15 minuter.
HTTP 403 och Cloudflare 1010: uppdatera .github/scripts/publish.py från startmallen och pusha igen. Äldre kopior saknar klientnamnet som Cloudflare behöver.
Namnet syns, men ingen analys: kontrollera att rätt dag och del är godkända hos AoC, att du ändrat choose-your-language i solution.json och att lösningen ligger under rätt days/NN/manual/ eller days/NN/agent/.
Fel AoC-konto är redan anslutet: kontakta oss så hjälper vi dig rätta kopplingen.

Till checklistan · Så räknas resultaten · Spelregler