refactor: number nested folders by sidebar position

- rename hand-authored folders to use numeric prefixes matching their
  _category_.json position (concepts, guides, reference, api, apps, solana)
- update autogen-reference.sh and graphql.ts to write into prefixed paths
- delete orphan docs/api/05-airdrops; promote docs/api/airdrops into the slot
- add Bob Vaults section to docs/concepts/14-fees.mdx (fixes broken anchor)
- drop dead baseURL from graphql-markdown plugin config
- ignore .ai/ in prettier

Author: PaulRBerg

.prettierignore

@@ -1,4 +1,5 @@
 # directories
+.ai
 .docusaurus
 .serena
 build

cli/autogen-reference.sh

@@ -20,11 +20,11 @@ root=$(pwd)
 bun install --cwd "$root/repos/evm-monorepo"
 
 # Define the contracts directories
-airdrops=docs/reference/airdrops/contracts
-bob=docs/reference/bob/contracts
-flow=docs/reference/flow/contracts
-lockup=docs/reference/lockup/contracts
-utils=docs/reference/utils/contracts
+airdrops=docs/reference/03-airdrops/contracts
+bob=docs/reference/05-bob/contracts
+flow=docs/reference/04-flow/contracts
+lockup=docs/reference/02-lockup/contracts
+utils=docs/reference/06-utils/contracts
 
 # Delete the current contracts documentations
 for dir in $airdrops $bob $flow $lockup $utils; do
@@ -57,7 +57,7 @@ fix_utils_abstract() {
 }
 
 lint() {
-  contracts=docs/reference/$1/contracts
+  contracts=${!1}
 
   # Cache find result to avoid redundant filesystem scan
   all_md_files=$(find $contracts -type f -name "*.md")
@@ -90,7 +90,7 @@ run() {
   cd "$root"
 
   # Define the contracts directory
-  contracts=docs/reference/$repo/contracts
+  contracts=${!repo}
 
   # Copy over the auto-generated files
   rsync --archive \
@@ -125,7 +125,7 @@ run() {
     sd "\{SablierMerkleSignature\}" "[SablierMerkleSignature](/$contracts/abstracts/abstract.SablierMerkleSignature.md)" $all_md_files
 
     # The Airdrops has certain references to the Lockup
-    sd "\{SablierLockup\}" "[SablierLockup](/reference/lockup/contracts/contract.SablierLockup.md)" $all_md_files
+    sd "\{SablierLockup\}" "[SablierLockup](/$lockup/contract.SablierLockup.md)" $all_md_files
 
     # Airdrops-only evm-utils abstract
     sd "\bAdminable\b" "[Adminable](/$contracts/abstracts/abstract.Adminable.md)" $all_md_files
@@ -149,7 +149,7 @@ run() {
     sd "/$lockup/interfaces/interface.InvalidStreamInCancelMultiple.md" "/$lockup/interfaces/interface.ISablierLockup.md#invalidstreamincancelmultiple" $all_md_files
     sd "/node_modules/forge-std/src/mocks/MockERC721.sol/contract.MockERC721.md" "https://eips.ethereum.org/EIPS/eip-165" $all_md_files
     sd "/node_modules/@arbitrum/token-bridge-contracts/contracts/tokenbridge/libraries/ERC165.sol/abstract.ERC165.md#supportsinterface" "https://eips.ethereum.org/EIPS/eip-165" $all_md_files
-    # TODO: retarget to /reference/utils/contracts/contract.SablierComptroller.md now that the page exists
+    # TODO: retarget to /reference/06-utils/contracts/contract.SablierComptroller.md now that the page exists
     sd "/node_modules/@sablier/evm-utils/docs/reference/lockup/contracts/contract.SablierComptroller.md#supportsinterface" "https://eips.ethereum.org/EIPS/eip-165" $all_md_files
 
     # Rewrite Unicode-art math in LockupMath natspec to KaTeX-compatible LaTeX.
@@ -192,7 +192,7 @@ run() {
 
   # Fix external contract references that don't have docs
   if [ "$repo" = "lockup" ]; then
-    # TODO: retarget to /reference/utils/contracts/contract.SablierComptroller.md now that the page exists
+    # TODO: retarget to /reference/06-utils/contracts/contract.SablierComptroller.md now that the page exists
     sd "\[SablierComptroller\]\(/$lockup/contract\.SablierComptroller\.md\)" "**SablierComptroller**" $all_md_files
     sd "/node_modules/@sablier/evm-utils[^\"]*contract\.SablierComptroller\.md[^\"]*" "https://eips.ethereum.org/EIPS/eip-165" $all_md_files
   fi

cli/commands/autogen/graphql.ts

@@ -11,6 +11,12 @@ import type { CliOptions } from "../../types";
 
 const CHAIN_ID_SEPOLIA = 11_155_111;
 
+// Numeric prefix encodes the sidebar position; keep in sync with `docs/api/` folders.
+const INDEXER_FOLDER: Record<Indexer.IndexerKey, string> = {
+  airdrops: "05-airdrops",
+  streams: "04-streams",
+};
+
 type Category = {
   /** @see https://docusaurus.io/feature-requests/p/hiding-parts-of-docs-in-autogenerated-sidebar */
   className?: "hidden";
@@ -131,7 +137,7 @@ function cleanupDocs(docsPaths: string[]): void {
 }
 
 async function generateEnvio(indexer: Indexer.IndexerKey): Promise<string> {
-  const docsPath = `./docs/api/${indexer}/graphql/envio`;
+  const docsPath = `./docs/api/${INDEXER_FOLDER[indexer]}/graphql/envio`;
   const schemaURL = getIndexerEnvio({ chainId: CHAIN_ID_SEPOLIA, indexer }).endpoint.url;
 
   await runCommand(docsPath, schemaURL);
@@ -140,7 +146,7 @@ async function generateEnvio(indexer: Indexer.IndexerKey): Promise<string> {
 }
 
 async function generateGraph(indexer: Indexer.IndexerKey): Promise<string> {
-  const docsPath = `./docs/api/${indexer}/graphql/the-graph`;
+  const docsPath = `./docs/api/${INDEXER_FOLDER[indexer]}/graphql/the-graph`;
   const schemaURL = getIndexerGraph({ chainId: CHAIN_ID_SEPOLIA, indexer }).testingURL;
 
   await runCommand(docsPath, schemaURL);

config/plugins.ts

@@ -32,11 +32,10 @@ type GraphQLMarkdownOptions = GraphQLMarkdownCliOptions & Partial<PluginOptions>
 const graphqlMarkdown: [string, GraphQLMarkdownOptions] = [
   "@graphql-markdown/docusaurus",
   /**
-   * Some settings will be overridden by the CLI.
+   * The CLI provides `--base` and `--schema` per invocation; everything below is shared config.
    * @see https://graphql-markdown.dev/docs/settings
    */
   {
-    baseURL: "./docs/api/streams/the-graph",
     homepage: "static/graphql-overview.md",
     loaders: {
       UrlLoader: {