From d49f730299ec6a493e3cd02406a700c1c2cdd45b Mon Sep 17 00:00:00 2001
From: tiennm99 <tiennm99@outlook.com>
Date: Thu, 13 Aug 2026 13:52:38 +0700
Subject: [PATCH] docs: show include_org_repos in the runnable examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The input reached both reference tables but neither example, so anyone
copying the workflow YAML or the CLI invocation would not learn the knob
exists. Add it to the Action example with a note on when to flip it, and
add a second CLI example alongside the existing one.

Add CLAUDE.md recording the five surfaces a config knob has to reach —
flag, action input, entrypoint translation, README tables *and*
examples, architecture doc — since the examples are the step that got
missed here. Also note the demo gallery's hardcoded card list and the
GitHub API ceilings the fetch pipeline works around.
---
 CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  7 +++++++
 2 files changed, 59 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..f7e783b7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,52 @@
+# ghstats
+
+Single-binary Go CLI that renders GitHub profile cards as SVG, wrapped by a
+published GitHub Action. `main.go` parses flags → `internal/github` fetches →
+`internal/card` renders → `internal/theme` supplies palettes.
+
+## Adding or changing a config knob
+
+A new flag, input, or default is not done when the code compiles. Every knob
+has a surface in five places, and a change that lands in some but not all of
+them ships a half-wired feature or a README that lies:
+
+1. `main.go` — the CLI flag
+2. `action.yml` — the matching Action input and its default
+3. `entrypoint.sh` — the `INPUT_*` → flag translation
+4. `README.md` — **both** reference tables (Action inputs, CLI flags) **and
+   the runnable examples**: the workflow YAML under "Use as a GitHub Action"
+   and the `ghstats …` command under "Use as a CLI"
+5. `docs/system-architecture.md` — when the knob changes the fetch pipeline
+   or its query cost
+
+The examples are the step most often missed, and they are what people copy.
+Grep the flag name across the repo before calling the change complete; every
+hit that is a reference table or example should mention it.
+
+## Behavior changes are user-visible
+
+The Action is published to the Marketplace, so existing callers get whatever
+`@v1` points at. Default-off for anything that moves numbers on already-
+rendered cards, and say so in the input description. Releases are tag-driven:
+push `vX.Y.Z`, and `release.yml` tests, builds, and force-moves the floating
+`v1` tag.
+
+## Cards and the demo gallery
+
+Adding a card means updating `internal/card/card.go`, the card table in
+`README.md`, and the layout in `.github/workflows/demo.yml` — the demo
+generator embeds a hardcoded list of SVGs, so a new card renders into every
+theme directory but stays invisible in the gallery until it is added there.
+Per-theme pages mirror the table layout in the author's profile README at
+`tiennm99/tiennm99`.
+
+## GitHub API constraints worth remembering
+
+- `commitContributionsByRepository` caps at 100 repos per query and truncates
+  silently. Contribution years are queried by quarter, and a saturated quarter
+  is re-asked by month. Only widen windows with that ceiling in mind.
+- `contributionCalendar` is clipped to the exact `from`/`to`, with no
+  week-boundary spillover, so disjoint windows never double-count days.
+- Test files named `*_windows_test.go` (or any GOOS/GOARCH suffix) are
+  silently excluded from the build on other platforms — `go test` reports
+  "ok" while running nothing.
diff --git a/README.md b/README.md
index d358e9b4..e5d2fd95 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,7 @@ jobs:
           tz: Asia/Saigon
           include_forks: "true"
           include_private: "true"
+          include_org_repos: "false"  # "true" also counts org repos you administer (token needs read:org)
           commit_changes: "true"
 ```
 
@@ -152,6 +153,12 @@ export GITHUB_TOKEN=ghp_xxx
 ghstats -user tiennm99 -themes dracula,github_dark -tz Asia/Saigon -out output
 ```
 
+Add `-include-org-repos` to also count org-owned repos you administer:
+
+```sh
+ghstats -user tiennm99 -themes dracula -include-org-repos -out output
+```
+
 | Flag                | Default         | Description                                                            |
 | ------------------- | --------------- | ---------------------------------------------------------------------- |
 | `-user`             | *(required)*    | GitHub username                                                        |