Add include_code remark plugin for auto-synced ONBOARDING.md snippets

ONBOARDING.md code snippets were manually copied from source files with
hardcoded line numbers that went stale on every contract change. This adds
the include_code remark plugin to extract snippets from source at build time.

- Add docs:start/docs:end markers to 7 source files (19 marker pairs)
- Create docs/ONBOARDING.src.md with #include_code directives
- Install include_code, remark, remark-cli; add .remarkrc.mjs config
- Add yarn docs:build script to regenerate ONBOARDING.md
- Update CLAUDE.md with new docs workflow instructions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: critesjosh

.gitignore

@@ -7,4 +7,5 @@ log/
 codegenCache.json
 store/
 .tsbuildinfo
-.env
+.env
+.include-code-cache/

.remarkrc.mjs

@@ -0,0 +1,12 @@
+import { remarkIncludeCode } from 'include_code';
+
+export default {
+  plugins: [
+    [remarkIncludeCode, {
+      codeDir: './src',
+      repository: { owner: 'AztecProtocol', name: 'aztec-starter' },
+      commitTag: 'main',
+      validation: 'error',
+    }]
+  ]
+};

CLAUDE.md

@@ -148,10 +148,27 @@ When updating the Aztec version, update all of these locations:
 
 ## ONBOARDING.md Maintenance
 
-This repo includes an `ONBOARDING.md` that serves as a progressive tutorial for Ethereum developers learning Aztec. **When making code changes, check if `ONBOARDING.md` references the changed code** (line numbers, function signatures, code snippets, struct definitions) and update it accordingly. Key sections that embed code:
+`ONBOARDING.md` is **generated** — do not edit it directly. Edit `docs/ONBOARDING.src.md` instead, then rebuild:
 
-- Phase 1 (1.3-1.6): Contract storage, public/private functions, game flow table
-- Phase 2 (2.3): Noir test patterns and helpers
-- Phase 5 (5.1-5.3): Guided exercises with code examples
-- Appendix A: File map table
-- Appendix B: Commands table
+```bash
+yarn docs:build    # remark docs/ONBOARDING.src.md -o ONBOARDING.md
+```
+
+The source file uses `#include_code` directives (via the `include_code` remark plugin) to extract code snippets from source files at build time. Source files have `// docs:start:<name>` / `// docs:end:<name>` marker pairs that define snippet boundaries.
+
+**When making code changes:**
+
+1. Source code snippets update automatically on rebuild — no manual copy needed
+2. If you add/remove/rename a marker, update the corresponding `#include_code` directive in `docs/ONBOARDING.src.md`
+3. Run `yarn docs:build` to regenerate `ONBOARDING.md`
+4. Phase 5 exercises and non-source prose still need manual updates in `docs/ONBOARDING.src.md`
+
+**Files with `docs:start`/`docs:end` markers:**
+
+- `src/main.nr` — `storage`, `constructor`, `create-game`, `join-game`, `play-round`, `validate-and-play-round`, `finish-game`, `validate-finish-game`, `finalize-game`
+- `src/race.nr` — `race-struct`, `calculate-winner`
+- `src/game_round_note.nr` — `game-round-note`, `game-round-note-new`
+- `src/test/utils.nr` — `test-setup`
+- `src/test/helpers.nr` — `allocation-strategies`, `setup-helpers`
+- `src/test/pod_racing.nr` — `test-initializer`, `test-fail-too-many-points`
+- `src/utils/sponsored_fpc.ts` — `get-sponsored-fpc`

ONBOARDING.md

@@ -32,6 +32,7 @@
     "test::devnet": "AZTEC_ENV=devnet yarn test:js",
     "test:js": "rm -rf store/pxe && NODE_NO_WARNINGS=1 node --experimental-vm-modules $(yarn bin jest) --no-cache --runInBand --config jest.integration.config.json",
     "test:nr": "aztec test",
+    "docs:build": "remark docs/ONBOARDING.src.md -o ONBOARDING.md",
     "update-readme-version": "node ./.github/scripts/update-readme-version.js"
   },
   "dependencies": {
@@ -51,7 +52,10 @@
     "@types/jest": "^29.5.11",
     "@types/mocha": "^10.0.6",
     "@types/node": "^22.15.1",
+    "include_code": "^0.1.0",
     "jest": "^29.7.0",
+    "remark": "^15.0.1",
+    "remark-cli": "^12.0.1",
     "ts-jest": "^29.1.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.4.4"

docs/ONBOARDING.src.md

@@ -1,5 +1,6 @@
 use aztec::{macros::notes::note, protocol::{traits::Packable, address::AztecAddress}};
 
+// docs:start:game-round-note
 // GameRoundNote is a private note that stores a player's point allocation for one round
 // These notes remain private until the player calls finish_game to reveal their totals
 //
@@ -25,8 +26,10 @@ pub struct GameRoundNote {
     // The player who created this note (only they can read it)
     pub owner: AztecAddress,
 }
+// docs:end:game-round-note
 
 impl GameRoundNote {
+    // docs:start:game-round-note-new
     // Creates a new note with the player's round choices
     // This note gets stored privately and can only be read by the owner
     pub fn new(track1: u8, track2: u8, track3: u8, track4: u8, track5: u8, round: u8, owner: AztecAddress) -> Self {
@@ -40,6 +43,7 @@ impl GameRoundNote {
             owner,
         }
     }
+    // docs:end:game-round-note-new
 
     // Helper method to access the note data
     pub fn get(self) -> Self {

package.json

@@ -37,6 +37,7 @@ pub contract PodRacing {
     global TOTAL_ROUNDS: u8 = 3; // Each game consists of 3 rounds
     global GAME_LENGTH: u32 = 300; // Games expire after 300 blocks
 
+    // docs:start:storage
     #[storage]
     struct Storage<Context> {
         // Contract administrator address
@@ -55,14 +56,18 @@ pub contract PodRacing {
         // Public leaderboard tracking career victories
         win_history: Map<AztecAddress, PublicMutable<u64, Context>, Context>,
     }
+    // docs:end:storage
 
+    // docs:start:constructor
     #[external("public")]
     #[initializer]
     fn constructor(admin: AztecAddress) {
         debug_log_format("Initializing PodRacing contract with admin {0}", [admin.to_field()]);
         self.storage.admin.write(admin);
     }
+    // docs:end:constructor
 
+    // docs:start:create-game
     // Creates a new game instance
     // The caller becomes player1 and waits for an opponent to join
     // Sets the game expiration to current block + GAME_LENGTH
@@ -85,7 +90,9 @@ pub contract PodRacing {
         );
         self.storage.races.at(game_id).write(game);
     }
+    // docs:end:create-game
 
+    // docs:start:join-game
     // Allows a second player to join an existing game
     // After joining, both players can start playing rounds
     #[external("public")]
@@ -99,7 +106,9 @@ pub contract PodRacing {
         let joined_game = maybe_existing_game.join(player2);
         self.storage.races.at(game_id).write(joined_game);
     }
+    // docs:end:join-game
 
+    // docs:start:play-round
     // Plays a single round by allocating points across 5 tracks
     // This is a PRIVATE function - the point allocation remains hidden from the opponent
     // Players must play rounds sequentially (round 1, then 2, then 3)
@@ -148,7 +157,9 @@ pub contract PodRacing {
             round,
         ));
     }
+    // docs:end:play-round
 
+    // docs:start:validate-and-play-round
     // Internal public function to validate and record that a player completed a round
     // Updates the public game state to track which round each player is on
     // Does NOT reveal the point allocation (that remains private)
@@ -163,7 +174,9 @@ pub contract PodRacing {
         // Increment the player's round counter (validates sequential play)
         self.storage.races.at(game_id).write(game_in_progress.increment_player_round(player, round));
     }
+    // docs:end:validate-and-play-round
 
+    // docs:start:finish-game
     // Called after all rounds are complete to reveal a player's total scores
     // This is PRIVATE - only the caller can read their own GameRoundNotes
     // The function sums up all round allocations per track and publishes totals
@@ -214,7 +227,9 @@ pub contract PodRacing {
             total_track5,
         ));
     }
+    // docs:end:finish-game
 
+    // docs:start:validate-finish-game
     // Internal public function to store a player's revealed track totals
     // Validates that the player hasn't already revealed their scores (all must be 0)
     // After both players call finish_game, all scores are public and can be compared
@@ -249,7 +264,9 @@ pub contract PodRacing {
             total_track5,
         ));
     }
+    // docs:end:validate-finish-game
 
+    // docs:start:finalize-game
     // Determines the winner after both players have revealed their scores
     // Can only be called after the game's end_block (time limit expired)
     // Compares track totals and declares the player who won more tracks as winner
@@ -276,6 +293,7 @@ pub contract PodRacing {
         );
         self.storage.win_history.at(winner).write(previous_wins + 1);
     }
+    // docs:end:finalize-game
 
     // Utility function: runs client-side in the PXE, not on-chain.
     // Reads the public game state and logs it via debug_log_format.

src/game_round_note.nr

@@ -4,6 +4,7 @@ use ::aztec::protocol::{
     traits::{Deserialize, Serialize, Packable, ToField},
 };
 
+// docs:start:race-struct
 // Race struct stores the public state of a game
 // This data is visible to everyone and tracks game progress
 #[derive(Deserialize, Serialize, Eq, Packable)]
@@ -37,6 +38,7 @@ pub struct Race {
     // Block number when the game expires (for timeout enforcement)
     pub end_block: u32,
 }
+// docs:end:race-struct
 
 impl Race {
     // Creates a new game with player1 set, waiting for player2 to join
@@ -250,6 +252,7 @@ impl Race {
         debug_log_format("End block: {0}", [self.end_block as Field]);
     }
 
+    // docs:start:calculate-winner
     // Determines the game winner by comparing track scores
     // Winner is whoever won more tracks (best of 5)
     //
@@ -305,4 +308,5 @@ impl Race {
             self.player2
         }
     }
+    // docs:end:calculate-winner
 }

src/main.nr

@@ -15,6 +15,7 @@ pub global TEST_GAME_ID_8: Field = 8;
 pub global TEST_GAME_ID_9: Field = 9;
 pub global TEST_GAME_ID_10: Field = 10;
 
+// docs:start:allocation-strategies
 // Common point allocations for testing
 // Balanced strategy: distribute points evenly
 pub unconstrained fn balanced_allocation() -> (u8, u8, u8, u8, u8) {
@@ -35,7 +36,9 @@ pub unconstrained fn defensive_allocation() -> (u8, u8, u8, u8, u8) {
 pub unconstrained fn max_allocation() -> (u8, u8, u8, u8, u8) {
     (5, 2, 1, 1, 0)
 }
+// docs:end:allocation-strategies
 
+// docs:start:setup-helpers
 // Helper to setup a game with two players
 pub unconstrained fn setup_two_player_game(
     env: &mut TestEnvironment,
@@ -77,3 +80,4 @@ pub unconstrained fn play_all_rounds_with_strategy(
         play_round_with_allocation(env, contract_address, player, game_id, round, allocations[i]);
     }
 }
+// docs:end:setup-helpers