docs: deepen thin chapters for claude quickstarts, codex analysis, and tiktoken

Author: johnxie

tutorials/claude-quickstarts-tutorial/04-browser-computer-use.md

@@ -7,27 +7,58 @@ parent: Claude Quickstarts Tutorial
 
 # Chapter 4: Browser and Computer Use
 
-Automation quickstarts demonstrate how Claude can execute browser and desktop actions.
+Browser and desktop control quickstarts are high leverage, but they require explicit safety boundaries.
+
+## Execution Loop
+
+A reliable automation loop is:
+
+1. inspect state (DOM snapshot, screenshot, focused window)
+2. plan a single concrete action
+3. execute action
+4. verify resulting state
+5. repeat until goal or stop condition
+
+This keeps errors localized and makes debugging straightforward.
 
 ## Browser Automation Pattern
 
-- navigate page
-- inspect DOM state
-- perform targeted interactions
-- verify outcome with assertions/screenshots
+Use short, verifiable actions:
+
+- navigate to known URL
+- wait for explicit selectors
+- fill one field at a time
+- verify expected text/state before continuing
+
+Avoid monolithic "do everything" instructions that hide failure points.
+
+## Computer-Use Risk Model
+
+Desktop automation should classify actions into risk tiers:
+
+| Tier | Example | Required Control |
+|:-----|:--------|:-----------------|
+| Low | read visible state | none or lightweight logging |
+| Medium | non-destructive clicks/type | confirmation on first use |
+| High | file deletion/send/submit | explicit human approval per action |
+
+## Guardrails
 
-## Safety Controls
+- strict domain and application allowlists
+- denylist destructive shortcuts by default
+- short action timeouts with retry limits
+- full action log with screenshots for audit
 
-- strict allowlist of domains/actions
-- confirmation step for destructive operations
-- timeout and retry policies for flaky pages
+## Failure Recovery
 
-## Computer Use Notes
+When state diverges from expectations:
 
-Computer control workflows are powerful but require strong human-in-the-loop controls for production.
+- stop action sequence
+- capture current state artifacts
+- ask for user confirmation or corrected target
 
 ## Summary
 
-You can now apply Claude to UI automation with explicit safety boundaries.
+You can now run browser/computer-use workflows with a deterministic control loop and practical safety gates.
 
 Next: [Chapter 5: Autonomous Coding Agents](05-autonomous-coding-agents.md)

tutorials/claude-quickstarts-tutorial/05-autonomous-coding-agents.md

@@ -7,27 +7,56 @@ parent: Claude Quickstarts Tutorial
 
 # Chapter 5: Autonomous Coding Agents
 
-Coding quickstarts show how to combine planning, execution, and persistence across sessions.
+Autonomous coding quickstarts work best when planning and execution are separated.
 
-## Two-Agent Pattern
+## Two-Agent Baseline
 
-- **Initializer agent**: clarifies goals and constraints.
-- **Coding agent**: implements changes and tests them.
+- **Planner/Initializer**: clarifies objective, constraints, acceptance criteria
+- **Executor/Coder**: performs edits, runs tests, reports concrete outcomes
 
-## Persistence Strategy
+This split reduces context confusion and improves handoff quality.
 
-- Store progress in git commits/branches.
-- Keep machine-readable task state.
-- Resume work from explicit checkpoints.
+## Checkpointed Workflow
+
+Use explicit checkpoints after meaningful work units:
+
+1. expected outcome
+2. files changed
+3. tests run and result
+4. unresolved risks
+5. next step
+
+Store checkpoints in version control or task state files so runs can resume reliably.
+
+## Autonomous Loop Pattern
+
+```text
+plan -> edit -> test -> summarize diff -> checkpoint -> continue or stop
+```
+
+Stop conditions should be explicit:
+
+- acceptance criteria met
+- blocking test failures
+- unsafe/conflicting instructions
 
 ## Quality Controls
 
-- run tests before each checkpoint
-- require diff summaries
-- block merges on failing validations
+| Control | Purpose |
+|:--------|:--------|
+| Required tests per checkpoint | Prevent hidden regressions |
+| Diff summary requirement | Improve reviewability |
+| Policy checks before merge | Enforce org standards |
+| Max iteration budget | Prevent runaway loops |
+
+## Common Failure Modes
+
+- planning omitted, leading to aimless edits
+- too many edits before first test run
+- missing rollback strategy for failed experiments
 
 ## Summary
 
-You can now design persistent coding-agent flows with practical guardrails.
+You can now design autonomous coding flows that are resumable, test-driven, and reviewable.
 
 Next: [Chapter 6: Production Patterns](06-production-patterns.md)

tutorials/claude-quickstarts-tutorial/08-enterprise-operations.md

@@ -7,23 +7,53 @@ parent: Claude Quickstarts Tutorial
 
 # Chapter 8: Enterprise Operations
 
-This chapter closes the quickstarts track with enterprise operations patterns.
+This chapter closes the quickstarts path with an enterprise operating model.
 
-## Operations Baseline
+## Multi-Tenant Governance Baseline
 
-- per-tenant quotas and usage governance
-- centralized prompt/config version management
-- incident runbooks for provider degradation
+- per-tenant rate and token quotas
+- model access policies by environment
+- centralized prompt/config versioning
+- approval workflows for high-risk tool classes
 
-## Compliance and Auditability
+## Auditability Requirements
 
-- trace IDs across request, tool, and response paths
-- immutable audit logs for high-risk actions
-- retention and redaction policies by environment
+Capture immutable run metadata:
+
+- request and trace IDs
+- model/version used
+- tools invoked and arguments (with redaction)
+- policy decisions and approval events
+- final outputs and status
+
+Without this, incident response and compliance review become guesswork.
+
+## Reliability and Incident Readiness
+
+- define SLOs for latency and success rate
+- maintain runbooks for provider degradation
+- implement fallback behavior for critical workflows
+- test rollback paths during release drills
+
+## Security and Data Handling
+
+| Area | Enterprise Control |
+|:-----|:-------------------|
+| Secrets | centralized secret management, no inline keys |
+| Data retention | environment-specific retention windows |
+| PII handling | classification + redaction policy |
+| Access control | least privilege by role/team |
+
+## Adoption Playbook
+
+1. launch read-only assistant capabilities first
+2. baseline quality/cost metrics
+3. introduce mutating actions with approvals
+4. expand scope by team with policy templates
 
 ## Final Summary
 
-You now have an end-to-end path from prototype quickstarts to enterprise-grade Claude systems.
+You now have a practical blueprint for scaling Claude quickstarts into governed enterprise operations.
 
 Related:
 - [Anthropic Skills Tutorial](../anthropic-skills-tutorial/)

tutorials/codex-analysis-platform/07-automation-pipelines.md

@@ -7,28 +7,47 @@ nav_order: 7
 
 # Chapter 7: Automation Pipelines
 
-This chapter covers integrating analysis outputs into automated engineering pipelines.
+This chapter covers operationalizing analysis outputs inside CI/CD and scheduled workflows.
 
-## Pipeline Integrations
+## Pipeline Integration Layers
 
-- CI checks for static analysis regressions
-- nightly repository-wide indexing refresh jobs
-- pull-request annotations with symbol-impact summaries
+1. **Pull Request checks**: fail on new high-severity analysis findings
+2. **Nightly index refresh**: rebuild code graph and dependency metadata
+3. **Report publishing**: generate trend dashboards and team-level summaries
 
-## Reliability Patterns
+## PR Workflow Pattern
 
-- checkpoint incremental state between runs
-- retry transient parser/index failures with backoff
-- isolate language workers to prevent cross-language contention
+```text
+new PR -> scoped analysis -> annotate changed files -> enforce policy thresholds
+```
 
-## Data Products
+Use changed-file scoping for fast feedback and reserve full-repo scans for scheduled jobs.
 
-- architecture drift reports
-- dependency risk dashboards
-- trend metrics for complexity and ownership
+## Reliability Controls
+
+- checkpoint index state between runs
+- retry transient parser/network failures with backoff
+- isolate language workers to prevent cross-language failures
+- time-box expensive graph traversals
+
+## Data Products for Engineering Leadership
+
+- architecture drift alerts
+- ownership hotspot reports
+- dependency risk trendlines
+- complexity deltas by repository area
+
+## Operational Metrics
+
+| Metric | Why It Matters |
+|:-------|:---------------|
+| analysis duration | CI throughput and developer UX |
+| stale-index ratio | data freshness confidence |
+| parser failure rate | source-coverage reliability |
+| policy violation trend | risk posture over time |
 
 ## Summary
 
-You can now operationalize analysis artifacts in continuous engineering workflows.
+You can now embed code analysis into continuous delivery with measurable reliability.
 
 Next: [Chapter 8: Production Rollout](08-production-rollout.md)

tutorials/codex-analysis-platform/08-production-rollout.md

@@ -7,23 +7,50 @@ nav_order: 8
 
 # Chapter 8: Production Rollout
 
-This chapter finalizes the platform with production rollout, governance, and scaling strategy.
+This chapter finalizes rollout strategy, governance, and long-term operations.
 
-## Rollout Plan
+## Rollout Phasing
 
-- phase by repository size and team adoption risk
-- start with read-only insights before enforcement
-- add policy gates only after baseline stabilization
+Start with low-risk adoption:
 
-## Platform Operations
+1. read-only insights and dashboards
+2. non-blocking PR annotations
+3. soft policy thresholds with override process
+4. hard enforcement after baseline stabilization
 
-- monitor analysis latency and queue depth
-- track stale index percentage
-- alert on parser/version incompatibilities
+## Governance Model
+
+- define policy owners per rule class
+- separate policy authoring from enforcement runtime
+- version policy bundles with change approval
+- maintain documented exception process
+
+## Capacity and Scaling
+
+- shard analysis queues by repository and language
+- isolate heavy graph jobs from latency-sensitive PR checks
+- precompute frequently requested dependency paths
+
+## Incident Response Playbook
+
+Prepare for:
+
+- parser version regressions
+- stale or corrupt index snapshots
+- policy misconfiguration causing false positives
+- provider/toolchain outages
+
+Each failure mode needs rollback and communication steps.
+
+## Final Success Criteria
+
+- <target> CI latency overhead accepted by teams
+- stable policy precision/recall for key risk classes
+- clear ownership for platform and policy operations
 
 ## Final Summary
 
-You now have complete coverage for building, integrating, and operating a code intelligence platform.
+You now have an operational rollout framework for sustained code-intelligence platform adoption.
 
 Related:
 - [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)

tutorials/tiktoken-tutorial/06-chatml-and-tool-calls.md

@@ -7,27 +7,48 @@ parent: tiktoken Tutorial
 
 # Chapter 6: ChatML and Tool Call Accounting
 
-This chapter covers reliable token accounting for chat messages and tool-call payloads.
+Accurate token accounting for chat and tools is essential for reliability and cost predictability.
 
-## Message Accounting Pattern
+## Where Underestimation Happens
 
-- count tokens per message role (`system`, `user`, `assistant`)
-- include hidden scaffolding overhead in estimates
-- budget separately for tool arguments and tool results
+Teams often count only user-visible text and miss:
 
-## Practical Rule
+- role/message wrapper overhead
+- tool schema tokens
+- serialized tool arguments/results
+- retry-induced duplicate token spend
 
-Always estimate using the exact model encoding and message format you will send.
+## Accounting Strategy
 
-## Example
+1. tokenize each message with the exact target encoding
+2. add fixed wrapper overhead expected by your request format
+3. account for tool payloads separately
+4. include response-token guardband for retries/replans
+
+## Example Helper
 
 ```python
-def estimate_chat_tokens(messages, enc):
-    return sum(len(enc.encode(m["content"])) for m in messages)
+def estimate_chat_tokens(messages, encoding, fixed_overhead=0):
+    total = fixed_overhead
+    for m in messages:
+        total += len(encoding.encode(m.get("content", "")))
+    return total
 ```
 
+For tool flows, create separate counters for:
+
+- tool call request payload
+- tool response payload
+- assistant synthesis after tool result
+
+## Operational Use
+
+- preflight estimate before API call
+- reject or compress if over budget
+- log estimate vs actual for calibration
+
 ## Summary
 
-You can now avoid underestimating token cost in chat-tool workflows.
+You can now estimate chat/tool token usage with fewer hidden-cost surprises.
 
 Next: [Chapter 7: Multilingual Tokenization](07-multilingual-tokenization.md)