> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/docs/brand-blocklist.readme.md).

# Reviewing docs/brand-blocklist.txt

`docs/brand-blocklist.txt` is a **draft** written by an AI session per the drafting rule in `docs/ARCHITECTURE.md`'s "Brand blocklist" section. It has not been reviewed by the project owner yet. This document explains how to review it without this README itself becoming a second place where the sensitive terms are pasted — read the blocklist file directly for the actual entries.

## Why the file exists

CLAUDE.md's ground rule 1 bans third-party console brand names anywhere in this repo — code, comments, identifiers, docs, strings, commit messages, asset names, screenshots. `npm run brand-lint` (in `app/ui/scripts/`) enforces that rule by scanning the repo for the terms listed in the blocklist file. The blocklist file is the one deliberate, documented exception: it has to name the excluded terms so the tool can search for them everywhere else. Nothing else in the repo should ever restate an entry from that file.

## What to check when reviewing

1. **Coverage.** Read through each section header in the file (company; consoles/handhelds/hybrids; controllers/accessories; franchises/ characters; emulators; home-menu terms; online services; download stores) and confirm nothing relevant is missing that you know is at risk of showing up in code, docs, screenshots, or example file names (e.g. a test ROM's filename, a variable name copied from a wiki, a screenshot's window title).
2. **False positives.** Whole-word, case-insensitive matching with a trailing `*` for prefixes means short or generic-sounding entries can catch unrelated words. Skim for any entry that looks likely to trigger on ordinary English (a common word, a generic abbreviation used elsewhere in computing) and either remove it, make it more specific, or add an `allow: <glob> <term>` exemption for the legitimate use.
3. **The two Steamworks exemptions at the bottom of the file.** These allow two specific Steam Input identifier prefixes to be quoted verbatim, but only inside `crates/kouch-steam/`, matching the exception written into CLAUDE.md ground rule 1. Confirm the glob is still scoped to that one crate directory before approving — a broader glob would defeat the point of the blocklist.
4. **`profiles/` and `docs/FEATURE_PLAN.md`.** Per `docs/ARCHITECTURE.md`, `profiles/` is excluded from brand-lint entirely (it holds private local test data with real emulator names and paths), and `FEATURE_PLAN.md` is meant to stay a generic redaction. Neither should need entries added just for their own sake.
5. **New entries you add.** If you add a term while reviewing, follow the existing format: one term per line, `#` for comments, a trailing `*` for a prefix match, and keep new sensitive terms **only** in this file.

## After review

Once the owner is satisfied with the list:

1. Remove the "DRAFT" language at the top of `docs/brand-blocklist.txt` (or replace it with a short "reviewed by on " note).
2. Flip CI from warn mode to blocking mode: in `.github/workflows/ci.yml`, change the `BRAND_LINT_MODE=warn npm run brand-lint` step to run `npm run brand-lint` without the warn-mode environment variable.
3. Re-run `npm run brand-lint` locally against the full repo (not just `app/ui/`) to confirm nothing currently in the tree trips the now- blocking check.
4. Note the review in `docs/GO_PUBLIC_CHECKLIST.md` if that checklist is already underway.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kouch.dev/docs/brand-blocklist.readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.