# courts.guide

Site grounding for agents without the courts.guide repository: its seven charter files, unchanged except that headings sit two levels lower and every term id the pinned version defines, in the frontmatter blocks too, is followed by its label from the pinned version. The YAML blocks are therefore for reading, not parsing; the repo files are the source.

- Domain: courts.guide
- Pins: editorial-charter@1.3.1, portfolio-icp@1.0.0
- Repo: d1ed321415f94a46118d0fd567b9f9a5cf652e20 (committed 2026-10-03T14:38:02-07:00)
- Built 2026-10-05T03:25:29+00:00
- Pages: https://taxonomy.tfw.bz/sites/courts.guide/

## BRAND.md

Version 1.0.1 · status draft · sha256 95392b8606ddd658e67e334777c39a90805bef6821c2e3f59915f0a082154f34

```yaml
charter: 1
version: 1.0.1
profile: editorial-charter@1.3.1
domain: courts.guide
status: draft
reviewed_by: ""
archetype: charter:brand-archetype-explorer (explorer)
secondary_archetype: charter:brand-archetype-everyman (everyman)
claims:
  - id: c1
    text: The site routes players to the booking channel each city actually uses and takes no commission on bookings.
    basis: charter:claim-basis-documented (documented)
    source: strategy-work/projects/pickleballcourts.guide/decisions.md Decision 4; strategy/positioning.md section Key Differentiators
  - id: c2
    text: Venue records are merged from three sources (Playtomic, OpenStreetMap and DataForSEO Maps) and de-duplicated by location.
    basis: charter:claim-basis-documented (documented)
    source: PROJECT_MAP.md section Architecture Highlights; scripts/harvest_venues.py
```

### BRAND

#### Name and entity
courts.guide, a multi-sport venue directory for padel and pickleball in trending Asia-Pacific cities. The repo serves two sport domains, pickleballcourts.guide and padelcourts.guide, from one app (`apps/web/next.config.ts`). No entity home page or `about.manifest.json` exists yet.

#### Promise
Find a pickleball or padel court in your city and learn how people actually book it there.

#### Personality
The explorer, with an everyman streak: a local who knows which court is indoor, which is a converted badminton hall, and whether the booking happens by Facebook message, a LINE group or a government portal. Practical and community-first, not transactional.

#### Visual pointers
Brand kits: `brand/pbc/` (pickleballcourts.guide, "pb Disc") and `brand/pdc/` (padelcourts.guide, "p / net"). Tokens live in the app (`apps/web/tamagui.config.ts`). No `design/tokens.json` yet.

#### Do / Don't
Do: say how a court is booked in this city. Do: tag indoor or covered, and dedicated or converted. Do: show hours, price range and amenities from a source.
Don't: build a booking layer or take a commission in the first wave. Don't: publish US-first advice for an APAC city. Don't: call an LLM API to write content; drafts go through the in-session agent.

## VOICE.md

Version 1.1.1 · status draft · sha256 e198c729c124924cd71fcc5f81f6908a8301273de8bceb23169f93814790d1b0

```yaml
charter: 1
version: 1.1.1
profile: editorial-charter@1.3.1
domain: courts.guide
status: draft
reviewed_by: ""
register: charter:voice-register-consumer (consumer)
person: charter:voice-person-second (second person)
languages: [en, vi, th, zh]
addresses: [expat-players, travelling-players, new-players]
essence: Practical local knowledge in plain words, on where the courts are in this city and how people actually book them.
```

### VOICE: courts.guide

> Loaded by /humanizer (Step 0) and the content publishing gate (drafting Step 1
> + humanizer Step 3). If absent, both fall back to generic mode.
> Drafted by an agent on 2026-10-03 from `strategy-work/projects/pickleballcourts.guide/strategy/positioning.md` and `decisions.md`. No published prose exists to learn the voice from, so sections 3, 4 and 7 are proposals, not observations. Not signed off by the owner.

#### 1. Identity & Register
- Voice owner / who speaks: the courts.guide editors, second person to the reader. No named author.
- Register: product (a practical directory and guide)
- Language/locale: en (primary); vi, th and zh follow the city configs in `cities/*/config.json`
- One-line essence: "Practical local knowledge in plain words, on where the courts are in this city and how people actually book them."

#### 2. Audience
- Primary audience: expat players new to an Asia-Pacific city; travelling players and new players next
- Reader's job-to-be-done: find a court and learn how to book it the way this city does it
- Assume they know: that pickleball or padel exists and roughly how it is played. Always explain: the booking channel (Facebook message, LINE group, a government portal), whether a court is indoor, covered, dedicated or converted, and any local term on first use.

#### 3. Tone Axes  (mark where this voice sits)
- Formal   ──────●  Casual
- Authority ────●──  Peer
- Serious  ───●────  Playful
- Concise  ●───────  Expansive
- Default editorial_track: factual

#### 4. Person, POV & Cadence
- Person: second person (you) to the reader, third person for venues
- Sentence rhythm: short, concrete, steps for booking ("message the owner on Facebook, then confirm the hour")
- Paragraph length: 2 to 3 sentences
- Structural tics to keep: a "how to book here" line on every city and venue page. Avoid: US-centric assumptions, hype.
- Content rule: user-facing prose goes through the in-session agent, never an LLM API from a script (`AGENTS.md`).

#### 5. Lexicon
- Preferred terms: court, indoor, covered, dedicated court, converted court, dink, Erne, kitchen (as the glossary defines them), booking channel
- Banned phrases (beyond humanizer's generic list): gap, to be filled by the owner
- Capitalization & spelling rules: Sport names and city names follow the city configs (`Ho Chi Minh City`, `Bangkok`, `Singapore`). Domains stay lowercase, as in the wordmarks (`pickleballcourts`, `padelcourts`; `brand/pbc/README.md`, `brand/pdc/README.md`). The pickleball site name is "Pickleball Courts Guide" (`brand/pbc/web/site.webmanifest`). No padel site name is stated; the padel generator still copies the pickleball name.
- Domain-jargon level: low. Gloss each term once, as the glossary pages do.

#### 6. E-E-A-T / Experience Claims  (anchors gate Step 7)
- Authentic experience this voice can claim: none claimed. A sourced fact: the project decisions record that the founder is based in Ho Chi Minh City and has on-the-ground Asia-Pacific context (`decisions.md` Decision 2). Whether that supports a first-person experience claim is the owner's call.
- Named author + bio source: none. No named author and no named reviewer for this site; the live pages carry no byline (checked 2026-10-03).
- Quantified credential for bios: none. Do not invent one.
- Citation posture: venue facts from the venue's own page or booking channel, dated; sport rules from the national or international federation.
- Original-data hooks this voice owns: the merged venue data (Playtomic, OpenStreetMap, DataForSEO Maps) with indoor and dedicated tags, and city booking guides.
- "What I got wrong" angle: gap. Needs a real first-hand booking story from a named author.

#### 7. Gold-Standard Examples  (few-shot anchor, highest leverage)
Gap: no published page carries prose yet. The two guide files under `data/content/` are stubs that read "TODO: Full guide content." Replace this section with two verbatim paragraphs from the first published pages.

#### 8. Anti-References  (do NOT sound like)
- US-centric court-finder copy that ignores how booking works in Asia.
- Generic sports-portal listicles.
- Transactional booking-site urgency ("book now, only 2 slots left").

## STRATEGY.md

Version 1.0.1 · status draft · sha256 39b3cc262258f4e2c61711d49dd8b9091a5719c8015aaea3a0d61fa92fc82733

```yaml
charter: 1
version: 1.0.1
profile: editorial-charter@1.3.1
domain: courts.guide
status: draft
reviewed_by: ""
mission_shape: charter:mission-shape-serve-x-to-achieve-y (serve X to achieve Y)
horizon: charter:horizon-12m (12 months)
positioning:
  primary: charter:positioning-axis-locality (locality)
  secondary: [charter:positioning-axis-authority-depth (authority depth)]
audiences:
  - kind: charter:audience-kind-consumer (consumer)
    name: Expat players
    segment: expat-players
    job_to_be_done: Find a court and learn how to book it in a city where the booking method is unfamiliar.
  - kind: charter:audience-kind-consumer (consumer)
    name: Travelling players
    segment: travelling-players
    job_to_be_done: Find a court to play on while visiting an Asia-Pacific city.
  - kind: charter:audience-kind-consumer (consumer)
    name: New players
    segment: new-players
    job_to_be_done: Learn the rules, the vocabulary and the gear before the first game.
  - kind: charter:audience-kind-consumer (consumer)
    name: Local recreational players
    segment: local-recreational-players
    job_to_be_done: Find courts in their own language and city.
profile_required: true
```

### STRATEGY

#### Mission
We help players in Asia-Pacific cities find a pickleball or padel court and book it the way that city actually works, so a new player can get on court without a local contact.

#### Positioning
Locality first: Asia-Pacific only, city by city, with each city's real booking channel explained (Facebook messages in Ho Chi Minh City, a government portal in Singapore, LINE groups in Bangkok). Authority depth second: court data with indoor and covered tags, dedicated or converted court, and surface type, which general map search does not give. We concede the US market and any booking or payment layer. Sources: `strategy-work/projects/pickleballcourts.guide/strategy/positioning.md`, `decisions.md`.

#### Audiences
Expat players are English-speaking and active, new to a city. Travelling players want a court while visiting. New players want rules, vocabulary and gear. Local recreational players want courts in their own language. The source lists a fifth group, community organisers who run pickup games, which this draft folds into expat and local players. Sources: `positioning.md` section Target Audience.

#### Competitors
Pickleheads and Places2Play (USAPA) for US court finding. Pickleball Central for gear. Google Maps for generic local search. The Singapore Pickleball Association directory. Local Facebook groups, which are not searchable or indexable. Source: `positioning.md` section Competitive Landscape.

#### What we will not do
No booking layer in Wave 1, no commission on bookings, and no US-market focus. No LLM API calls to write user-facing content; drafts go through the in-session agent. Sources: `decisions.md` Decisions 2 and 4, `AGENTS.md`.

#### Bets for the horizon
1. Launch the Wave 1 city directories (Ho Chi Minh City, Singapore, Bangkok) with a city booking guide each (moves pageview_recorded).
2. Rank the city booking guides, which have no APAC-specific competition (moves gsc_clicks).
3. Ship the glossary and the beginner guides so new players stay past the court finder (moves content_engaged).

## AUDIENCE.md

Version 1.1.1 · status draft · sha256 c326ddf091ff9e8d35ea05fc89f71eb9857556e3798893545c346c58d0dc5656

```yaml
charter: 1
version: 1.1.1
profile: editorial-charter@1.3.1
domain: courts.guide
status: draft
reviewed_by: ""
segments:
  - slug: expat-players
    name: Expat players
    kind: charter:audience-kind-consumer (consumer)
    archetype: icp:first-time-experience-seeker (First-time experience seeker)
    priority: charter:segment-priority-primary (primary)
    job_to_be_done: Find a court and learn how to book it in a city where the booking method is unfamiliar.
    funnel_stages: [charter:funnel-stage-awareness (awareness), charter:funnel-stage-consideration (consideration), charter:funnel-stage-decision (decision)]
    languages: [en]
    regions: [VN, SG, TH]
    pains:
      - The booking method differs by city and is not explained anywhere.
      - Generic map search does not show indoor or covered courts.
    channels: [charter:channel-organic-search (organic search), charter:channel-community (community)]
    evidence:
      default: {basis: charter:evidence-basis-assumed (assumed), source: "agent draft 2026-10-03 from strategy-work/projects/pickleballcourts.guide/strategy/positioning.md (written April 2026 from the codebase, not from audience data)", as_of: 2026-10-03}
      regions: {basis: charter:evidence-basis-researched (researched), source: "strategy-work/projects/pickleballcourts.guide/decisions.md Decisions 2 and 3 (APAC focus, Wave 1 = Ho Chi Minh City, Singapore, Bangkok); the live pickleballcourts.guide and padelcourts.guide nav lists exactly these three cities (checked 2026-10-03)", as_of: 2026-10-03}

  - slug: travelling-players
    name: Travelling players
    kind: charter:audience-kind-consumer (consumer)
    archetype: icp:first-time-experience-seeker (First-time experience seeker)
    priority: charter:segment-priority-secondary (secondary)
    job_to_be_done: Find a court to play on while visiting an Asia-Pacific city.
    funnel_stages: [charter:funnel-stage-consideration (consideration), charter:funnel-stage-decision (decision)]
    languages: [en]
    regions: [VN, SG, TH]
    channels: [charter:channel-organic-search (organic search)]
    evidence:
      default: {basis: charter:evidence-basis-assumed (assumed), source: "agent draft 2026-10-03 from strategy-work/projects/pickleballcourts.guide/strategy/positioning.md (entry point 'Courts in [city]' pages)", as_of: 2026-10-03}
      regions: {basis: charter:evidence-basis-researched (researched), source: "strategy-work/projects/pickleballcourts.guide/decisions.md Decisions 2 and 3 (APAC focus, Wave 1 = Ho Chi Minh City, Singapore, Bangkok); the live pickleballcourts.guide and padelcourts.guide nav lists exactly these three cities (checked 2026-10-03)", as_of: 2026-10-03}

  - slug: new-players
    name: New players
    kind: charter:audience-kind-consumer (consumer)
    archetype: icp:first-time-experience-seeker (First-time experience seeker)
    priority: charter:segment-priority-secondary (secondary)
    job_to_be_done: Learn the rules, the vocabulary and the gear before the first game.
    funnel_stages: [charter:funnel-stage-awareness (awareness), charter:funnel-stage-consideration (consideration)]
    languages: [en]
    regions: [VN, SG, TH]
    channels: [charter:channel-organic-search (organic search)]
    evidence:
      default: {basis: charter:evidence-basis-assumed (assumed), source: "agent draft 2026-10-03 from strategy-work/projects/pickleballcourts.guide/strategy/positioning.md (beginner guides, rules, glossary)", as_of: 2026-10-03}
      regions: {basis: charter:evidence-basis-researched (researched), source: "strategy-work/projects/pickleballcourts.guide/decisions.md Decisions 2 and 3 (APAC focus, Wave 1 = Ho Chi Minh City, Singapore, Bangkok); the live pickleballcourts.guide and padelcourts.guide nav lists exactly these three cities (checked 2026-10-03)", as_of: 2026-10-03}

  - slug: local-recreational-players
    name: Local recreational players
    kind: charter:audience-kind-consumer (consumer)
    archetype: icp:unmapped (Unmapped)  # no pinned archetype fits a local regular who is not a first-timer
    priority: charter:segment-priority-watch (watch)
    job_to_be_done: Find courts in their own language and city.
    funnel_stages: [charter:funnel-stage-consideration (consideration), charter:funnel-stage-decision (decision)]
    languages: [vi, th]
    regions: [VN, TH]
    channels: [charter:channel-organic-search (organic search)]
    evidence:
      default: {basis: charter:evidence-basis-assumed (assumed), source: "agent draft 2026-10-03 from strategy-work/projects/pickleballcourts.guide/strategy/positioning.md ('native-language court finder') and cities/hcmc and cities/bangkok config locales", as_of: 2026-10-03}
```

### AUDIENCE

#### Expat players
English-speaking, active people new to an Asia-Pacific city who want a court and do not know how local booking works. Source: `strategy-work/projects/pickleballcourts.guide/strategy/positioning.md`.

#### Travelling players
Visitors to an Asia-Pacific city who want to play while there. They arrive through court pages for a city. Source: `positioning.md`.

#### New players
People getting into the sport who need the rules, scoring, vocabulary and equipment explained. Source: `positioning.md`.

#### Local recreational players
Residents who play for fitness and want courts in their own language. Watch segment: the Vietnamese and Thai locales exist in city config, and no data shows their reach. Source: `positioning.md`, `cities/*/config.json`.

#### Excluded audiences
Not written for: US players looking for a US court finder, and anyone expecting to book and pay for a court on the site. Source: `decisions.md` Decisions 2 and 4.

## MONETIZATION.md

Version 1.0.1 · status draft · sha256 53c151a96227f02ebd06877d23a0c122a9a2292f7a0c6a01f0620c4edd3f349c

```yaml
charter: 1
version: 1.0.1
profile: editorial-charter@1.3.1
domain: courts.guide
status: draft
reviewed_by: ""
revenue_lines:
  - slug: gear-affiliate
    name: Gear affiliate links, later wave
    type: charter:revenue-type-affiliate (affiliate)
    program_status: charter:program-status-unchecked (unchecked)
    commission_model: charter:commission-model-unknown (unknown)
    placements: [charter:placement-type-inline-link (inline link)]
    segments: [new-players]
    kpi_key: affiliate_clicked
    status: charter:revenue-status-idea (idea)
    share_band: charter:revenue-share-band-marginal (marginal)
    start_trigger: Owner decides how soon gear affiliate content comes, after community trust is established
    evidence:
      default: {basis: charter:evidence-basis-assumed (assumed), source: "agent draft 2026-10-03 from strategy-work/projects/pickleballcourts.guide/README.md ('Wave 1 monetization: zero'; open question 'Gear affiliate content, how soon'); no program was checked", as_of: 2026-10-03}
```

### MONETIZATION

#### Revenue model
Wave 1 earns nothing on purpose: community trust comes before revenue. The one line below is an idea taken from the project's open question about gear affiliate content. It is not planned, no program has been looked at, and the file holds no figures.

#### Disclosure rules
Any commercial relationship that shapes a page is disclosed on that page. No venue pays for a ranking in Wave 1. Source: `strategy-work/projects/pickleballcourts.guide/README.md`, `decisions.md`.

#### Not monetised
No booking fees, no commission on court bookings and no payment layer in Wave 1. The site routes players to the booking channel each city already uses. Source: `decisions.md` Decision 4, `positioning.md`.

#### Gear affiliate links, later wave
An idea only. Gear content (paddles, a gear budget calculator) is planned as a content cluster, and affiliate links on it have not been decided.

## KPI.md

Version 1.0.1 · status draft · sha256 6bad0e9b55557e221c8658c833815c0cd83f5a43e511bd047219df14e37e0505

```yaml
charter: 1
version: 1.0.1
profile: editorial-charter@1.3.1
domain: courts.guide
status: draft
reviewed_by: ""
template: charter:kpi-template-editorial-traffic (editorial traffic)
template_override: ""
kpis:
  - {key: pageview_recorded, role: charter:kpi-role-primary (primary)}
  - {key: gsc_clicks, role: charter:kpi-role-secondary (secondary)}
  - {key: gsc_impressions, role: charter:kpi-role-secondary (secondary)}
  - {key: avg_position, role: charter:kpi-role-secondary (secondary)}
  - {key: content_engaged, role: charter:kpi-role-secondary (secondary)}
  - {key: newsletter_subscribed, role: charter:kpi-role-secondary (secondary)}
  - {key: affiliate_clicked, role: charter:kpi-role-secondary (secondary)}
  - {key: crawl_errors, role: charter:kpi-role-guardrail (guardrail)}
  - {key: pages_indexed, role: charter:kpi-role-guardrail (guardrail)}
catalog_sha: 4304fc97e9ac457725bdc25dcbb724c36257a707cbb3c237b69cd3e7ba04ac39
```

### KPI

#### Why these metrics
Wave 1 earns nothing, so reach is what the site is run on, and pageview_recorded is the primary. gsc_clicks, gsc_impressions and avg_position show whether the city and booking-guide queries find the pages. content_engaged shows whether the glossary, guides and tools are used. newsletter_subscribed stays from the template: the strategy notes mention a court alerts newsletter or Telegram channel only as a mitigation idea, and the site emits no signup event. affiliate_clicked stays because the template requires it and reads zero until gear links are approved. crawl_errors and pages_indexed are the guardrails across many city and venue pages.

#### Reading guide
Read pageview_recorded weekly against the `(site)` target in kpi-mgmt once one exists. Rising pages_indexed with flat gsc_clicks means venue pages are indexed but do not match the query. The app emits no analytics events yet, so content_engaged needs instrumentation before it reads anything.

#### Review cadence
Quarterly, with the 12-month bets in STRATEGY.md.

## taxonomy/binding.yaml

Version 1.0.1 · status draft · sha256 d79baf5999a25e728ab5828614ae8e0ad03d7fc40eaeeb2427e0746dc7ab37e2

```yaml
charter: 1
version: 1.0.1
profile: editorial-charter@1.3.1
domain: courts.guide
status: draft
reviewed_by: ""
iab_content: ["iab:483"]
icp_profile: portfolio-icp@1.0.0
content_profile: null
languages: [en, vi, th, zh]
regions: [VN, SG, TH]
```