@urmzd/github-insights 2.0.0

package/.gitattributes

@@ -0,0 +1,28 @@
+# Enforce LF line endings for all text files
+* text=auto eol=lf
+
+# Ensure specific files use LF
+*.sh text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.rs text eol=lf
+*.toml text eol=lf
+*.go text eol=lf
+*.py text eol=lf
+*.js text eol=lf
+*.ts text eol=lf
+*.tsx text eol=lf
+*.jsx text eol=lf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary

package/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

package/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- Brief description of what this PR does and why -->
+
+## Changes
+
+<!-- List the key changes made -->
+
+-
+
+## Verification
+
+- [ ] `npm run ci` passes (fmt, lint, typecheck, test, build)
+- [ ] `npm run generate` runs locally without overwriting project README

package/.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  fmt:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run fmt
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm test
+
+  integrate:
+    name: Integration
+    needs: [fmt, lint, typecheck, test]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      models: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+
+      - name: Self-test action
+        uses: ./
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          commit-push: "false"
+          readme-path: "_README.md"
+
+      - name: Verify SVGs generated
+        run: |
+          if [ ! -f assets/insights/index.svg ]; then
+            echo "ERROR: assets/insights/index.svg was not generated"
+            exit 1
+          fi
+          echo "Self-test passed: assets/insights/index.svg generated"

package/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      force:
+        description: "Re-release the current tag (use when a previous release partially failed)"
+        type: boolean
+        default: false
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+      models: read
+
+  release:
+    name: Release
+    needs: ci
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - run: npm install -g npm@latest
+      - run: npm ci
+      - run: npm run build
+      - run: git add -f dist/
+      - run: tar -czf dist.tar.gz dist/
+
+      - name: Release
+        id: sr
+        uses: urmzd/semantic-release@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          force: ${{ inputs.force }}
+
+      - name: Publish to npm
+        if: steps.sr.outputs.released == 'true'
+        run: |
+          npm version "${{ steps.sr.outputs.version }}" --no-git-tag-version
+          npm publish --provenance --access public

package/.nvmrc

@@ -0,0 +1 @@
+22

package/.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/urmzd/semantic-release
+    rev: v0.4.0
+    hooks:
+      - id: conventional-commit-msg

package/AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+## Identity
+
+You are an agent working on **github-insights** — a GitHub Action that generates beautiful SVG metrics visualizations for GitHub profile READMEs. It produces language breakdowns, AI expertise analysis, contribution pulse, social badges, and signature projects.
+
+## Architecture
+
+TypeScript/Node.js GitHub Action using React JSX for SVG rendering.
+
+| File | Role |
+|------|------|
+| `src/index.ts` | Main action entry point |
+| `src/api.ts` | GitHub API interactions |
+| `src/metrics.ts` | Metric calculation logic |
+| `src/templates.ts` | SVG template generation |
+| `src/config.ts` | Configuration parsing (`github-insights.yml`) |
+| `src/readme.ts` | README generation |
+| `src/types.ts` | Type definitions (`UserConfig`, etc.) |
+| `src/components/` | 22+ component subdirectories for different metric types |
+| `action.yml` | GitHub Action definition |
+
+## Key Dependencies
+
+- `@actions/core`, `@actions/exec`, `@actions/github` — GitHub Action SDK
+- `smol-toml` — TOML config parsing
+- `@vercel/ncc` — Bundle to `dist/`
+- `vitest` — Testing
+- `biome` — Linting and formatting
+
+## Commands
+
+| Task | Command |
+|------|---------|
+| Build | `npm run build` (ncc bundle to dist/) |
+| Test | `npm test` (vitest) |
+| Type-check | `npm run typecheck` (tsc --noEmit) |
+| Lint | `npm run lint` (biome check) |
+| Format check | `npm run fmt` |
+| Format fix | `npm run fmt:fix` |
+| Generate locally | `npm run generate` (requires `gh auth`) |
+| Full CI | `npm run ci` (fmt + lint + typecheck + test + build) |
+
+## Code Style
+
+- TypeScript with strict mode, ES modules (`"type": "module"`)
+- Biome for formatting and linting (not ESLint/Prettier)
+- Node.js 22+ (`.nvmrc`)
+- Tests colocated as `*.test.ts` alongside source files
+- Components are React JSX returning SVG elements
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `assets/insights/index.svg` | Combined visualization |
+| `assets/insights/metrics-pulse.svg` | Contribution activity |
+| `assets/insights/metrics-languages.svg` | Language donut chart |
+| `assets/insights/metrics-expertise.svg` | AI expertise bars |
+| `assets/insights/metrics-complexity.svg` | Top projects by stars |
+| `assets/insights/metrics-contributions.svg` | External contributions |
+
+## Adding a New Component
+
+1. Create `src/components/<name>/` directory
+2. Add the component as a React JSX function returning SVG elements
+3. Add a corresponding `*.test.ts` file
+4. Wire it into `src/templates.ts` and `src/metrics.ts`
+5. Update `action.yml` if new inputs are needed

package/CHANGELOG.md

@@ -0,0 +1,260 @@
+# Changelog
+
+## 1.1.0 (2026-03-15)
+
+### Features
+
+- enrich project display with AI summaries, h3 headings, and complexity ranking ([93fdeed](https://github.com/urmzd/github-metrics/commit/93fdeed2c6277d29b8d65b69fb790ac8ec0eeaaf))
+
+### Documentation
+
+- **skill**: comprehensive rewrite of github-metrics agent skill ([4d641fd](https://github.com/urmzd/github-metrics/commit/4d641fd664190993cb0c4408d0eca35fd7cca41e))
+
+[Full Changelog](https://github.com/urmzd/github-metrics/compare/v1.0.1...v1.1.0)
+
+
+## 1.0.1 (2026-03-15)
+
+### Bug Fixes
+
+- **release**: use npm trusted publishing and add Apache-2.0 license field ([d181940](https://github.com/urmzd/github-metrics/commit/d181940db6debce9ffa0f4628a1c1f7db8bf48c4))
+
+[Full Changelog](https://github.com/urmzd/github-metrics/compare/v1.0.0...v1.0.1)
+
+
+## 1.0.0 (2026-03-15)
+
+### Breaking Changes
+
+- remove justfile build tool ([d126632](https://github.com/urmzd/github-metrics/commit/d126632c949d8081fc186aaa2c63ee44803b13f1))
+
+### Features
+
+- **types**: add complexity fields to ProjectItem ([638df32](https://github.com/urmzd/github-metrics/commit/638df328c8d58a2c51ca26709e1f6e7453d26d1b))
+- **index**: prioritize projects by technical complexity ([58ddc2a](https://github.com/urmzd/github-metrics/commit/58ddc2ac8a49bacd78e46da4a4d3356f16c5e4b0))
+- **metrics**: add project complexity scoring ([1e1a729](https://github.com/urmzd/github-metrics/commit/1e1a7298cd6a457f2235d56994968bf3973f208c))
+
+### Bug Fixes
+
+- **ci**: collapse varDefs chain to single line for biome compliance ([912a9d9](https://github.com/urmzd/github-metrics/commit/912a9d9290ae77d125161dbcd4bfcdb3633753ef))
+- **ci**: format long lines in metrics.ts for biome compliance ([60a9ae1](https://github.com/urmzd/github-metrics/commit/60a9ae1089c69251a478771db5eea01be74c2261))
+
+### Documentation
+
+- replace just commands with npm run across all documentation ([09675e5](https://github.com/urmzd/github-metrics/commit/09675e580974eb25740122da3f1797ce07cd7ba7))
+- add AGENTS.md and agent skill for Claude Code ([a7d6d05](https://github.com/urmzd/github-metrics/commit/a7d6d05045017429ec20394e222f895f1682df1c))
+
+### Refactoring
+
+- **api**: extract graphql client and refactor fetch functions ([62642d8](https://github.com/urmzd/github-metrics/commit/62642d81f9f5e4c0c687b59f7381df509ae49090))
+
+### Miscellaneous
+
+- regenerate dist bundle and example metrics ([59d7737](https://github.com/urmzd/github-metrics/commit/59d77373779e5ca51d8200bdcff36dbb8d185666))
+- **metrics**: update project sorting tests for complexity ranking ([004e14f](https://github.com/urmzd/github-metrics/commit/004e14f2b27455905801aba4967fc4860ca020cc))
+
+[Full Changelog](https://github.com/urmzd/github-metrics/compare/v0.6.0...v1.0.0)
+
+
+## 0.6.0 (2026-03-05)
+
+### Features
+
+- **examples**: generate template examples in subdirectories ([ff257e2](https://github.com/urmzd/github-metrics/commit/ff257e29045c5ae046a9d0a604b0fa91162fdca9))
+- **metrics**: classify projects by commit activity ([59d11a9](https://github.com/urmzd/github-metrics/commit/59d11a91faab801ad18859443a399a2a969b8cc1))
+- **api**: fetch commit contributions by repository ([42c2e2e](https://github.com/urmzd/github-metrics/commit/42c2e2ea50283305eb085d1b04ba87b115a06bee))
+
+### Bug Fixes
+
+- **ci**: format long lines in metrics.test.ts for biome compliance ([d889d64](https://github.com/urmzd/github-metrics/commit/d889d64870f1a3728d006c061d6f05a86b7bd449))
+
+### Miscellaneous
+
+- **metrics**: update generated metrics ([cdde265](https://github.com/urmzd/github-metrics/commit/cdde2657eb36d624fba5a96af1ba6ddb4a030dca))
+
+
+## 0.5.1 (2026-02-27)
+
+### Bug Fixes
+
+- use npm trusted publishing with OIDC instead of token ([dc81e99](https://github.com/urmzd/github-metrics/commit/dc81e993cfd3e7fdf777a5282d713364936713df))
+
+### Miscellaneous
+
+- **release**: v0.5.0 [skip ci] ([da30654](https://github.com/urmzd/github-metrics/commit/da306547f0a9c9ca8bb5e05ff89c973f3b4043b2))
+
+
+## 0.5.0 (2026-02-27)
+
+
+## 0.5.0 (2026-02-27)
+
+### Features
+
+- publish to npm on release ([152067e](https://github.com/urmzd/github-metrics/commit/152067e5f9c01100da7d1f6ac01544e92e30c26b))
+
+
+## 0.4.6 (2026-02-27)
+
+### Bug Fixes
+
+- distinguish active vs popular projects in AI preamble prompt ([b7cef11](https://github.com/urmzd/github-metrics/commit/b7cef11780f0ae93242bc2dc3cebddf16e9b122b))
+
+### Miscellaneous
+
+- standardize GitHub Actions workflows ([1937089](https://github.com/urmzd/github-metrics/commit/1937089fc291b42821e0e3a8366dd17ed2ce1742))
+- add sensitive paths to .gitignore ([006d95b](https://github.com/urmzd/github-metrics/commit/006d95bf711cf2a7fd0b083b86757a8546ca3533))
+
+
+## 0.4.5 (2026-02-20)
+
+### Bug Fixes
+
+- increase vertical spacing between text labels and bar SVGs ([3ff1b0d](https://github.com/urmzd/github-metrics/commit/3ff1b0de497cad1c211f3e901f0e48132dacd536))
+
+
+## 0.4.4 (2026-02-19)
+
+### Bug Fixes
+
+- separate labels and bars onto two lines to prevent text overlap ([f4bbe42](https://github.com/urmzd/github-metrics/commit/f4bbe42fc37015a7d0eced6ad8da55a59a5c22ca))
+
+
+## 0.4.3 (2026-02-18)
+
+### Bug Fixes
+
+- use first-person AI prompts and show usernames in social badges ([f0d6afd](https://github.com/urmzd/github-metrics/commit/f0d6afdbfbc39766f53fbbac922e1b8edbfe360b))
+
+### Refactoring
+
+- move template preview READMEs to examples/ directory ([35bfaf0](https://github.com/urmzd/github-metrics/commit/35bfaf0472d01da4758b4424e614931f3d9b8c42))
+
+
+## 0.4.2 (2026-02-17)
+
+### Bug Fixes
+
+- use gpt-4.1 model and fix lint warning in regex ([f369763](https://github.com/urmzd/github-metrics/commit/f369763f103ab0c55175cdcce8dfefe2e6ec5ce8))
+- prevent conversational filler in AI-generated preamble ([d3c6e55](https://github.com/urmzd/github-metrics/commit/d3c6e5572cb088ae56c5b33f750dc972f52f4504))
+
+
+## 0.4.1 (2026-02-14)
+
+### Bug Fixes
+
+- format chained method calls to satisfy biome formatter ([55cbf8f](https://github.com/urmzd/github-metrics/commit/55cbf8f6c13ab30b3c5bb0b0e636a0c232d8adad))
+- strip markdown code fences from AI-generated preamble ([35d879e](https://github.com/urmzd/github-metrics/commit/35d879edbd11bf7e6a999efbca927d4c529f4881))
+
+### Documentation
+
+- sync README and CONTRIBUTING with recent code changes ([c696f13](https://github.com/urmzd/github-metrics/commit/c696f130159795f1be5510173763f7b4be56de7b))
+- update badge examples in preamble generation prompt ([5548154](https://github.com/urmzd/github-metrics/commit/5548154b8b825ba2e7f10912d1393aa22fa936bf))
+
+### Miscellaneous
+
+- remove dist/ from version control ([f8ed3b3](https://github.com/urmzd/github-metrics/commit/f8ed3b3bf120603b768d00b345e4888482546df9))
+
+
+## 0.4.0 (2026-02-11)
+
+### Features
+
+- remove GitHub badge from preamble and add generation date to attribution ([2cfd311](https://github.com/urmzd/github-metrics/commit/2cfd3111e1c876f28c0c51e69e0fa4f8e1ef2b33))
+
+### Bug Fixes
+
+- resolve biome format and lint errors in CI pipeline ([4eee052](https://github.com/urmzd/github-metrics/commit/4eee052eac7f761f3858284c5eb5c08cb7fd1e68))
+- prevent text-bar overlap in expertise SVG ([22d3c45](https://github.com/urmzd/github-metrics/commit/22d3c45980934927a914509800d4b016c5b6b119))
+
+### Miscellaneous
+
+- add preamble regression tests for generateReadme ([894a653](https://github.com/urmzd/github-metrics/commit/894a653e0580e56d508de5d0380f1e30a371a2e7))
+- update semantic-release action to v1 ([b2331d7](https://github.com/urmzd/github-metrics/commit/b2331d77511012e9aa44cedeb57c9903560582e2))
+- gitignore _README.md temp artifact ([aa9fa57](https://github.com/urmzd/github-metrics/commit/aa9fa577b840a811e94a3bc5c2cac981e00fbbaf))
+
+
+## 0.3.1 (2026-02-11)
+
+### Bug Fixes
+
+- use relative SVG paths in generated README ([d280808](https://github.com/urmzd/github-metrics/commit/d280808a2851d0e836a7bc528b64a487270744a4))
+
+
+## 0.3.0 (2026-02-11)
+
+### Features
+
+- replace generate-readme flag with readme-path, add project docs ([07edd44](https://github.com/urmzd/github-metrics/commit/07edd440b432c06ee4bc4f1568a8dd8e6a7516ad))
+- add proficiency scores to expertise bars and disable commit-push locally ([7f5413f](https://github.com/urmzd/github-metrics/commit/7f5413f2cba99869215731acceaed0b0e07eb572))
+
+### Miscellaneous
+
+- update biome schema to 2.3.14 and apply formatting fixes ([8bf1856](https://github.com/urmzd/github-metrics/commit/8bf18561e113819fa650dbf3993b038b84149307))
+- update metrics ([26f3f66](https://github.com/urmzd/github-metrics/commit/26f3f6636518ba5429adb259dc9355d6520ed5db))
+
+
+## 0.2.0 (2026-02-11)
+
+### Features
+
+- add force re-release support to release workflow ([46fbe6d](https://github.com/urmzd/github-metrics/commit/46fbe6d60483a818af58b70b3c80b7d8f216ca7d))
+
+### Refactoring
+
+- replace ESLint + Prettier with Biome ([9a98708](https://github.com/urmzd/github-metrics/commit/9a98708596a48f527ff846d8943d0c8955712fb6))
+
+### Miscellaneous
+
+- update metrics ([b98290c](https://github.com/urmzd/github-metrics/commit/b98290caa3fc4fe0dd67a682f9e7a7c6fa547c3c))
+
+
+## 0.1.2 (2026-02-10)
+
+### Bug Fixes
+
+- move build steps to workflow and upload dist tarball as release artifact ([a553318](https://github.com/urmzd/github-metrics/commit/a5533186cd5da788afc460ca4e44dd08075a58de))
+
+### Contributors
+
+- @urmzd
+
+
+## 0.1.1 (2026-02-10)
+
+### Bug Fixes
+
+- let semantic-release handle floating major-version tags natively ([4706c57](https://github.com/urmzd/github-metrics/commit/4706c5735fc2ed4979d4c0d4b75464ae13ff7ddc))
+
+### Contributors
+
+- @urmzd
+
+
+## 0.1.0 (2026-02-10)
+
+### Features
+
+- replace hardcoded tech classification with AI-curated tech highlights ([ebcca06](https://github.com/urmzd/github-metrics/commit/ebcca0645e4fcd1446ff05c206d45df893c80ae9))
+- initial implementation of github-metrics action ([6e99dfd](https://github.com/urmzd/github-metrics/commit/6e99dfd58ddc42ca3d936dbaecc289475af1e5de))
+
+### Bug Fixes
+
+- use node24 runtime for GitHub Actions compatibility ([7bf6836](https://github.com/urmzd/github-metrics/commit/7bf683645e781feb5d0e63ce1447e572e4db209b))
+- add eslint config and fix lint errors ([e134c7e](https://github.com/urmzd/github-metrics/commit/e134c7eb785dddd07994663578b210f8e295eb04))
+
+### Documentation
+
+- move full dashboard SVG to end of README ([0ad66d0](https://github.com/urmzd/github-metrics/commit/0ad66d03f831c32a952be2cc286079bfbcfd96bc))
+- add README, CONTRIBUTING, LICENSE and fix release workflow ([e82f406](https://github.com/urmzd/github-metrics/commit/e82f406b4568c41867930535b4da0be4663d9dfb))
+
+### Miscellaneous
+
+- stop tracking dist/ and let semantic-release build it ([f4e3d9f](https://github.com/urmzd/github-metrics/commit/f4e3d9f554cc46939511f6c8059aef8998e161d4))
+- rebuild dist/ to match source ([150a848](https://github.com/urmzd/github-metrics/commit/150a84882f34c3a8f361b66e8a641861b57795a4))
+- fix prettier formatting in 6 source files ([6776b08](https://github.com/urmzd/github-metrics/commit/6776b083965f1aafabfd8b5caf07cc5e23e70a1d))
+- apply formatter and linter fixes ([3b53ce5](https://github.com/urmzd/github-metrics/commit/3b53ce5f54ceb4bcb75fb9cde48325e8a46a5968))
+
+### Contributors
+
+- @urmzd

package/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing
+
+## Project Structure
+
+```
+src/
+  index.ts          # Entry point — orchestrates fetch, transform, render, write
+  api.ts            # GitHub GraphQL/REST API calls + AI model calls
+  metrics.ts        # Data aggregation and section definitions
+  config.ts         # TOML config parsing (UserConfig)
+  readme.ts         # Profile README generation
+  parsers.ts        # Dependency manifest parsers
+  types.ts          # Shared type definitions
+  jsx-factory.ts    # Custom JSX factory for SVG rendering
+  jsx.d.ts          # JSX type declarations
+  theme.ts          # Theme constants (colors, fonts, spacing)
+  svg-utils.ts      # SVG utility functions
+  __fixtures__/
+    repos.ts        # Test fixture data
+  components/       # SVG rendering components
+    full-svg.tsx    # Combines sections into a single SVG
+    section.tsx     # Individual section renderer
+    donut-chart.tsx # Language donut chart
+    bar-chart.tsx   # Horizontal bar chart
+    tech-highlights.tsx  # Expertise bars
+    stat-cards.tsx  # Contribution stat cards
+    project-cards.tsx    # Project cards
+    contribution-cards.tsx # External contribution cards
+    style-defs.tsx  # Shared SVG style definitions
+```
+
+## Adding a New Metric Section
+
+1. If your section needs a new render component, create it in `src/components/`. It should export a function that takes data + a `y` offset and returns `{ svg: string, height: number }`.
+
+2. Add your section to `buildSections` in `src/metrics.ts` (line ~91). Each section is a `SectionDef` (`src/types.ts:54`):
+
+```typescript
+sections.push({
+  filename: "metrics-your-section.svg",
+  title: "Your Section",
+  subtitle: "Description of this section",
+  renderBody: (y: number) => renderYourComponent(data, y),
+});
+```
+
+3. The section is automatically included in the combined `index.svg` and written as a standalone SVG.
+
+## Adding a Package Parser
+
+Package parsers extract dependency names from manifest files so the AI expertise analysis can see what libraries you use.
+
+1. Create a `PackageParser` implementation (`src/types.ts:113`):
+
+```typescript
+export const MyParser: PackageParser = {
+  filenames: ["my-manifest.json"],
+  parseDependencies(text) {
+    // Parse and return dependency names
+    return [];
+  },
+};
+```
+
+2. Add it to the `PARSERS` array in `src/parsers.ts` (line ~129).
+
+3. Add the manifest filename to `MANIFEST_FILES` in `src/api.ts` (line ~13) so the API fetches it from repos.
+
+## Adding Config Fields
+
+1. Add the field to the `UserConfig` interface in `src/types.ts` (line ~126).
+
+2. Add parsing logic in `parseUserConfig` in `src/config.ts` — follow the existing pattern of type-checking and trimming.
+
+3. Use the new field wherever needed (e.g., in `src/index.ts`, `src/readme.ts`, or `src/metrics.ts`).
+
+## Testing
+
+- Tests use [Vitest](https://vitest.dev/) with `*.test.ts` and `*.test.tsx` naming conventions
+- Use `.test.tsx` for tests that exercise JSX components (e.g., `src/components/section.test.tsx`)
+- Run tests: `npm test`
+- Tests live alongside source files (e.g., `src/config.test.ts`, `src/components/donut-chart.test.tsx`)
+
+## Code Style
+
+- Enforced by [Biome](https://biomejs.dev/) — run `npm run fmt` to check, `npm run fmt:fix` to auto-fix
+- Run `npm run ci` before submitting a PR to catch formatting, lint, type, and test issues