updated

CLAUDE.md

@@ -116,3 +116,4 @@ From experience with this repository:
 - `reports/claude-skills-for-larger-mono-repos.md`: Skills discovery and loading behavior in monorepos (static vs dynamic discovery)
 - `reports/claude-agent-memory.md`: Agent memory frontmatter — persistent memory scopes (user, project, local) for subagents
 - `reports/claude-advanced-tool-use.md`: Advanced tool use patterns — Programmatic Tool Calling (PTC), Tool Search, Tool Use Examples
+- `reports/claude-usage-and-rate-limits.md`: Usage commands (`/usage`, `/extra-usage`, `/cost`), rate limits, and pay-as-you-go overflow billing

README.md

@@ -1,9 +1,7 @@
 # claude-code-best-practice
 practice makes claude perfect
 
-<a href="https://github.com/shanraisshan/claude-code-best-practice/stargazers">
+![Last Updated](https://img.shields.io/badge/Last_Updated-Feb_26%2C_2026_10%3A45_AM_PKT-white?style=flat&labelColor=555) <a href="https://github.com/shanraisshan/claude-code-best-practice/stargazers"><img src="https://img.shields.io/github/stars/shanraisshan/claude-code-best-practice?style=social" alt="GitHub Stars"></a>
-  <img src="https://img.shields.io/github/stars/shanraisshan/claude-code-best-practice?style=social" alt="GitHub Stars">
-</a>
 
 <p align="center">
   <img src="!/claude-jumping.svg" alt="Claude Code mascot jumping" width="120" height="100">
@@ -36,6 +34,18 @@ practice makes claude perfect
 
 **Extension Overview:** See [Extend Claude Code](https://code.claude.com/docs/en/features-overview) for when to use each feature and how they layer together.
 
+## 💎 HIDDEN GEMS
+
+> Reports that are frequently updated as Claude Code evolves.
+
+| Report | Description |
+|--------|-------------|
+| [Claude Code Commands Reference](reports/claude-commands.md) | Complete reference of all slash commands, keyboard shortcuts, and input modes |
+| [Claude Code Settings Reference](reports/claude-settings.md) | Comprehensive guide to all `settings.json` configuration options |
+| [Agents Frontmatter Reference](reports/claude-agents-frontmatter.md) | Complete reference of all agent (`.claude/agents/`) frontmatter fields |
+| [Commands Frontmatter Reference](reports/claude-commands-frontmatter.md) | Complete reference of all command (`.claude/commands/`) frontmatter fields |
+| [Skills Frontmatter Reference](reports/claude-skills-frontmatter.md) | Complete reference of all skill (`.claude/skills/`) frontmatter fields |
+
 ## MY EXPERIENCE
 
 ■ **Workflows**
@@ -138,14 +148,14 @@ See [weather-orchestration-architecture](weather-orchestration/weather-orchestra
 | `/compact` | `/context` | `/model` | `/plan` | `/config` |
 | `/clear` | `/cost` | `/memory` | `/doctor` | `/rewind` |
 
-[**See Complete List →**](reports/live/agent-command-skills/claude-commands.md)
+[**See Complete List →**](reports/claude-commands.md)
 
 
 ## CLAUDE SETTINGS
 
 | | |
 |---|---|
-| [**Claude Settings**](reports/live/claude-settings.md) | [**Global vs Project Settings**](reports/claude-global-vs-project-settings.md) |
+| [**Claude Settings**](reports/claude-settings.md) | [**Global vs Project Settings**](reports/claude-global-vs-project-settings.md) |
 
 
 ## MCP SERVERS FOR DAILY USE
@@ -164,19 +174,6 @@ Research (Context7/DeepWiki) -> Debug (Playwright/Chrome) -> Document (Excalidra
 
 ## REPORTS
 
-### Live Reports
-> Reports that are frequently updated as Claude Code evolves.
-
-| Report | Description |
-|--------|-------------|
-| [Claude Code Commands Reference](reports/live/agent-command-skills/claude-commands.md) | Complete reference of all slash commands, keyboard shortcuts, and input modes |
-| [Claude Code Settings Reference](reports/live/claude-settings.md) | Comprehensive guide to all `settings.json` configuration options |
-| [Agents Frontmatter Reference](reports/live/agent-command-skills/claude-agents-frontmatter.md) | Complete reference of all agent (`.claude/agents/`) frontmatter fields |
-| [Commands Frontmatter Reference](reports/live/agent-command-skills/claude-commands-frontmatter.md) | Complete reference of all command (`.claude/commands/`) frontmatter fields |
-| [Skills Frontmatter Reference](reports/live/agent-command-skills/claude-skills-frontmatter.md) | Complete reference of all skill (`.claude/skills/`) frontmatter fields |
-
-### Reports
-
 | Report | Description |
 |--------|-------------|
 | [Agent SDK vs CLI System Prompts](reports/claude-agent-sdk-vs-cli-system-prompts.md) | Why Claude CLI and Agent SDK outputs may differ—system prompt architecture and determinism |
@@ -188,3 +185,9 @@ Research (Context7/DeepWiki) -> Debug (Playwright/Chrome) -> Document (Excalidra
 | [Agent Memory Frontmatter](reports/claude-agent-memory.md) | Persistent memory scopes (`user`, `project`, `local`) for subagents — enabling agents to learn across sessions |
 | [Boris Cherny's 12 Customization Tips](reports/claude-boris-tips-feb-26.md) | 12 ways to customize Claude Code — from terminal config to plugins, agents, hooks, and output styles |
 | [Advanced Tool Use Patterns](reports/claude-advanced-tool-use.md) | Programmatic Tool Calling (PTC), Tool Search, and Tool Use Examples |
+| [Usage, Rate Limits & Extra Usage](reports/claude-usage-and-rate-limits.md) | Usage commands (`/usage`, `/extra-usage`, `/cost`), rate limits, and pay-as-you-go overflow billing |
+| [Claude Code Commands Reference](reports/claude-commands.md) | Complete reference of all slash commands, keyboard shortcuts, and input modes |
+| [Claude Code Settings Reference](reports/claude-settings.md) | Comprehensive guide to all `settings.json` configuration options |
+| [Agents Frontmatter Reference](reports/claude-agents-frontmatter.md) | Complete reference of all agent (`.claude/agents/`) frontmatter fields |
+| [Commands Frontmatter Reference](reports/claude-commands-frontmatter.md) | Complete reference of all command (`.claude/commands/`) frontmatter fields |
+| [Skills Frontmatter Reference](reports/claude-skills-frontmatter.md) | Complete reference of all skill (`.claude/skills/`) frontmatter fields |

reports/claude-agents-frontmatter.md

@@ -4,8 +4,8 @@ Quick-reference tables for defining subagents in `.claude/agents/*.md`.
 
 <table width="100%">
 <tr>
-<td><a href="../../">← Back to Claude Code Best Practice</a></td>
+<td><a href="../">← Back to Claude Code Best Practice</a></td>
-<td align="right"><img src="../../!/claude-jumping.svg" alt="Claude" width="60" /></td>
+<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
 </tr>
 </table>
 

reports/claude-commands-frontmatter.md

@@ -4,8 +4,8 @@ Quick-reference tables for defining custom commands in `.claude/commands/<name>.
 
 <table width="100%">
 <tr>
-<td><a href="../../">← Back to Claude Code Best Practice</a></td>
+<td><a href="../">← Back to Claude Code Best Practice</a></td>
-<td align="right"><img src="../../!/claude-jumping.svg" alt="Claude" width="60" /></td>
+<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
 </tr>
 </table>
 

reports/claude-commands.md

@@ -4,8 +4,8 @@ A comprehensive reference of all available slash commands in Claude Code's inter
 
 <table width="100%">
 <tr>
-<td><a href="../../">← Back to Claude Code Best Practice</a></td>
+<td><a href="../">← Back to Claude Code Best Practice</a></td>
-<td align="right"><img src="../../!/claude-jumping.svg" alt="Claude" width="60" /></td>
+<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
 </tr>
 </table>
 

reports/claude-skills-frontmatter.md

@@ -4,8 +4,8 @@ Quick-reference tables for defining skills in `.claude/skills/<name>/SKILL.md`.
 
 <table width="100%">
 <tr>
-<td><a href="../../">← Back to Claude Code Best Practice</a></td>
+<td><a href="../">← Back to Claude Code Best Practice</a></td>
-<td align="right"><img src="../../!/claude-jumping.svg" alt="Claude" width="60" /></td>
+<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
 </tr>
 </table>
 

reports/claude-usage-and-rate-limits.md

@@ -0,0 +1,108 @@
+# Claude Code: Usage, Rate Limits & Extra Usage
+
+Understanding how usage limits work in Claude Code and how to keep working when you hit them.
+
+<table width="100%">
+<tr>
+<td><a href="../">← Back to Claude Code Best Practice</a></td>
+<td align="right"><img src="../!/claude-jumping.svg" alt="Claude" width="60" /></td>
+</tr>
+</table>
+
+---
+
+## Overview
+
+Claude Code on subscription plans (Pro, Max 5x, Max 20x) has usage limits that reset on a rolling window. Three built-in slash commands help you monitor and manage usage:
+
+| Command | Description | Available To |
+|---------|-------------|--------------|
+| `/usage` | Check plan limits and rate limit status | Pro, Max 5x, Max 20x |
+| `/extra-usage` | Configure pay-as-you-go overflow when limits are hit | Pro, Max 5x, Max 20x |
+| `/cost` | Show token usage and spending for the current session | API key users |
+
+---
+
+## `/usage` — Check Your Limits
+
+Shows your current plan's usage limits and rate limit status. Useful for checking how much capacity you have left before hitting a limit.
+
+---
+
+## `/extra-usage` — Keep Working Past Limits
+
+The `/extra-usage` command configures **pay-as-you-go overflow billing** so Claude Code continues working seamlessly when you hit your plan's rate limits, instead of blocking you.
+
+### How It Works
+
+1. You hit your plan's rate limit (limits reset every 5 hours)
+2. If extra usage is enabled with available funds, Claude Code continues without interruption
+3. Overflow tokens are billed at **standard API rates**, separate from your subscription fee
+
+### Setting It Up
+
+The `/extra-usage` command in the CLI will guide you through configuration. You can also configure it on the web at **Settings > Usage** on claude.ai:
+
+1. Enable extra usage
+2. Add a payment method
+3. Set a **monthly spending cap** (or choose unlimited)
+4. Optionally add **prepaid funds** with auto-reload when balance drops below a threshold
+
+### Key Details
+
+| Detail | Value |
+|--------|-------|
+| Daily redemption limit | $2,000/day |
+| Billing | Separate from subscription, at standard API rates |
+| Limit reset window | Every 5 hours |
+
+### Known Issue
+
+As of February 2026, the `/extra-usage` CLI command is [undocumented](https://github.com/anthropics/claude-code/issues/12396) and may open a sign-in window without clear configuration options. Configuring through the **claude.ai web interface** is the more reliable path for now.
+
+---
+
+## `/cost` — Session Spending (API Users)
+
+For users authenticating with an API key (not a subscription plan), `/cost` shows:
+
+- Total cost for the current session
+- API duration and wall time
+- Token usage breakdown
+- Code changes made
+
+This command is not relevant for Pro/Max subscription users.
+
+---
+
+## Fast Mode and Extra Usage
+
+Fast mode (`/fast`) uses Claude Opus 4.6 with faster output. It has a special billing relationship with extra usage:
+
+- Fast mode usage is **always billed to extra usage** from the first token
+- This applies even if you have remaining usage on your subscription plan
+- Fast mode does not consume your plan's included rate limits
+
+This means you need extra usage enabled and funded to use `/fast`.
+
+---
+
+## CLI Startup Flags
+
+Two startup flags relate to usage budgets (API key users only, print mode):
+
+| Flag | Description |
+|------|-------------|
+| `--max-budget-usd <AMOUNT>` | Maximum dollar amount for API calls before stopping |
+| `--max-turns <NUMBER>` | Limit number of agentic turns |
+
+See [CLI Startup Flags Reference](claude-cli-startup-flags.md) for the full list.
+
+---
+
+## Sources
+
+- [Extra usage for paid Claude plans — Claude Help Center](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)
+- [Using Claude Code with your Pro or Max plan — Claude Help Center](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
+- [/extra-usage slash command is undocumented — GitHub Issue #12396](https://github.com/anthropics/claude-code/issues/12396)
+- [Claude Code CLI Reference](https://code.claude.com/docs/en/cli-reference)