Skip to content

Commit 71e4097

Browse files
authored
docs: sync with goclaw source changes c651cde5..b1f6eadf (EN+VI+ZH) (#56)
Major updates aligned with new goclaw subsystems: - advanced/hooks-quality-gates.md: rewrite for new lifecycle hooks system (7 events, 3 handler types) - advanced/context-pruning.md: reframe as opt-in (requires cache-ttl mode) - advanced/tts-voice.md: add ElevenLabs model variants, agent-level voice config, STT note - reference/websocket-protocol.md: add hooks.* RPC methods and config.defaults - reference/rest-api.md: add TTS/github-releases endpoints, remove stale skill-apply - reference/database-schema.md: bump to v55, add hooks/hook_agents/hook_executions/tenant_hook_budget tables, vault scope CHECK - deployment/upgrading.md: add migrations 050-055 - getting-started/what-is-goclaw.md: add ACP Provider, Hooks System, Audio/TTS Manager - core-concepts/how-goclaw-works.md: add Hooks Dispatcher, Audio/TTS Manager - channels/pancake.md: add 8 new config fields Also: - .claude/skills/goclaw-docs-audit/mapping.json: extend coverage for audio/security/updater/webui/facebook/bgalert subsystems and docs/01-24 source files - build-llms.js: generate llms-full.txt for all 3 languages (EN/VI/ZH) - llms.txt + llms-full.txt × 3: regen and sync entries for hooks-quality-gates and system-prompt-anatomy
1 parent b1150d7 commit 71e4097

38 files changed

Lines changed: 45191 additions & 33711 deletions

.claude/skills/goclaw-docs-audit/mapping.json

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
{"pattern": "internal/channels/zalo/*", "docs": ["channels/zalo-oa.md", "channels/zalo-personal.md", "troubleshooting/channels.md"], "priority": "medium"},
3434
{"pattern": "internal/channels/whatsapp/*", "docs": ["channels/whatsapp.md", "troubleshooting/channels.md"], "priority": "medium"},
3535
{"pattern": "internal/channels/pancake/*", "docs": ["channels/pancake.md", "troubleshooting/channels.md"], "priority": "high"},
36+
{"pattern": "internal/channels/facebook/*", "docs": ["channels/facebook.md", "troubleshooting/channels.md"], "priority": "medium"},
3637
{"pattern": "internal/channels/slack/*", "docs": ["channels/slack.md", "troubleshooting/channels.md"], "priority": "medium"},
3738
{"pattern": "internal/channels/media/*", "docs": ["advanced/media-generation.md"], "priority": "low"},
3839
{"pattern": "internal/channels/typing/*", "docs": ["channels/overview.md"], "priority": "low"},
@@ -80,6 +81,18 @@
8081
{"pattern": "internal/skills/*", "docs": ["advanced/skills.md"], "priority": "medium"},
8182
{"pattern": "internal/sandbox/*", "docs": ["advanced/sandbox.md", "advanced/exec-approval.md"], "priority": "low"},
8283
{"pattern": "internal/tts/*", "docs": ["advanced/tts-voice.md"], "priority": "low"},
84+
{"pattern": "internal/audio/elevenlabs/*", "docs": ["advanced/tts-voice.md"], "priority": "medium"},
85+
{"pattern": "internal/audio/minimax/*", "docs": ["advanced/tts-voice.md"], "priority": "medium"},
86+
{"pattern": "internal/audio/openai/*", "docs": ["advanced/tts-voice.md"], "priority": "medium"},
87+
{"pattern": "internal/audio/edge/*", "docs": ["advanced/tts-voice.md"], "priority": "medium"},
88+
{"pattern": "internal/audio/music/*", "docs": ["advanced/media-generation.md"], "priority": "low"},
89+
{"pattern": "internal/audio/stt/*", "docs": ["advanced/tts-voice.md", "core-concepts/tools-overview.md"], "priority": "medium"},
90+
{"pattern": "internal/audio/*", "docs": ["advanced/tts-voice.md", "advanced/media-generation.md"], "priority": "medium"},
91+
{"pattern": "internal/security/*", "docs": ["deployment/security-hardening.md"], "priority": "medium"},
92+
{"pattern": "internal/updater/*", "docs": ["deployment/upgrading.md", "getting-started/installation.md"], "priority": "medium"},
93+
{"pattern": "internal/webui/*", "docs": ["getting-started/web-dashboard-tour.md"], "priority": "low"},
94+
{"pattern": "internal/bgalert/*", "docs": ["deployment/observability.md"], "priority": "low"},
95+
{"pattern": "internal/store/*", "docs": ["reference/database-schema.md"], "priority": "low"},
8396
{"pattern": "internal/permissions/*", "docs": ["agents/sharing-and-access.md", "advanced/api-keys-rbac.md", "advanced/usage-quota.md"], "priority": "medium"},
8497
{"pattern": "internal/config/*", "docs": ["reference/config-reference.md", "reference/environment-variables.md", "getting-started/configuration.md"], "priority": "medium"},
8598
{"pattern": "internal/workspace/*", "docs": ["agent-teams/creating-managing-teams.md", "advanced/sandbox.md"], "priority": "medium"},
@@ -123,12 +136,35 @@
123136
{"pattern": ".github/workflows/release*", "docs": ["deployment/upgrading.md", "getting-started/installation.md"], "priority": "low"},
124137

125138
{"pattern": "docs/00-architecture*", "docs": ["getting-started/what-is-goclaw.md", "core-concepts/how-goclaw-works.md"], "priority": "high"},
139+
{"pattern": "docs/01-agent-loop*", "docs": ["core-concepts/agents-explained.md", "core-concepts/how-goclaw-works.md", "agents/system-prompt-anatomy.md", "advanced/context-pruning.md"], "priority": "high"},
140+
{"pattern": "docs/02-providers*", "docs": ["providers/overview.md", "providers/*.md"], "priority": "high"},
141+
{"pattern": "docs/03-tools*", "docs": ["core-concepts/tools-overview.md", "advanced/custom-tools.md"], "priority": "high"},
142+
{"pattern": "docs/04-gateway-protocol*", "docs": ["reference/websocket-protocol.md", "reference/rest-api.md"], "priority": "high"},
143+
{"pattern": "docs/05-channels*", "docs": ["channels/overview.md", "channels/INDEX.md"], "priority": "high"},
144+
{"pattern": "docs/06-store*", "docs": ["reference/database-schema.md"], "priority": "high"},
145+
{"pattern": "docs/07-bootstrap*", "docs": ["agents/summoning-bootstrap.md", "agents/context-files.md"], "priority": "medium"},
146+
{"pattern": "docs/08-scheduling*", "docs": ["advanced/scheduling-cron.md"], "priority": "medium"},
147+
{"pattern": "docs/09-security*", "docs": ["deployment/security-hardening.md", "advanced/api-keys-rbac.md"], "priority": "high"},
148+
{"pattern": "docs/10-tracing*", "docs": ["deployment/observability.md"], "priority": "medium"},
149+
{"pattern": "docs/11-agent-teams*", "docs": ["agent-teams/*"], "priority": "high"},
150+
{"pattern": "docs/12-extended-thinking*", "docs": ["advanced/extended-thinking.md"], "priority": "medium"},
151+
{"pattern": "docs/13-ws-team-events*", "docs": ["agent-teams/team-messaging.md", "reference/websocket-protocol.md"], "priority": "medium"},
152+
{"pattern": "docs/14-skills-runtime*", "docs": ["advanced/skills.md"], "priority": "high"},
153+
{"pattern": "docs/15-core-skills*", "docs": ["advanced/skills.md"], "priority": "medium"},
154+
{"pattern": "docs/16-skill-publishing*", "docs": ["advanced/skills.md"], "priority": "medium"},
126155
{"pattern": "docs/17-changelog*", "docs": ["deployment/upgrading.md"], "priority": "high"},
156+
{"pattern": "docs/18-http-api*", "docs": ["reference/rest-api.md"], "priority": "high"},
157+
{"pattern": "docs/19-websocket-rpc*", "docs": ["reference/websocket-protocol.md"], "priority": "high"},
158+
{"pattern": "docs/20-api-keys*", "docs": ["advanced/api-keys-rbac.md"], "priority": "high"},
127159
{"pattern": "docs/21-agent-evolution*", "docs": ["advanced/agent-evolution.md"], "priority": "high"},
128160
{"pattern": "docs/22-v3-http*", "docs": ["reference/rest-api.md"], "priority": "high"},
129161
{"pattern": "docs/23-multi-tenant*", "docs": ["core-concepts/multi-tenancy.md"], "priority": "high"},
130162
{"pattern": "docs/24-knowledge-vault*", "docs": ["advanced/knowledge-vault.md"], "priority": "high"},
163+
{"pattern": "docs/agent-hooks*", "docs": ["advanced/hooks-quality-gates.md"], "priority": "high"},
164+
{"pattern": "docs/agent-identity*", "docs": ["agents/user-overrides.md", "agents/sharing-and-access.md"], "priority": "medium"},
165+
{"pattern": "docs/packages-github*", "docs": ["advanced/skills.md", "deployment/security-hardening.md"], "priority": "medium"},
131166
{"pattern": "docs/model-steering*", "docs": ["advanced/model-steering.md", "agents/system-prompt-anatomy.md"], "priority": "high"},
167+
{"pattern": "examples/hooks/*", "docs": ["advanced/hooks-quality-gates.md"], "priority": "low"},
132168

133169
{"pattern": "README.md", "docs": ["getting-started/what-is-goclaw.md"], "priority": "medium"},
134170
{"pattern": "CLAUDE.md", "docs": ["getting-started/what-is-goclaw.md"], "priority": "low"},

advanced/context-pruning.md

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Context pruning is distinct from [session compaction](../core-concepts/sessions-
1717

1818
## How Pruning Triggers
1919

20-
Pruning runs automatically on every agent request unless explicitly disabled with `mode: "off"`. The flow:
20+
Pruning is **opt-in** — it only runs when `mode: "cache-ttl"` is set on the agent. The flow:
2121

2222
```
2323
history → limitHistoryTurns → pruneContextMessages → sanitizeHistory → LLM
@@ -76,12 +76,12 @@ This placeholder is configurable. Hard clear can also be disabled entirely.
7676

7777
## Configuration
7878

79-
Context pruning is **on by default**. To disable it, set `mode: "off"` in the agent config.
79+
Context pruning is **opt-in**. To enable it, set `mode: "cache-ttl"` in the agent config.
8080

8181
```json
8282
{
8383
"contextPruning": {
84-
"mode": "off"
84+
"mode": "cache-ttl"
8585
}
8686
}
8787
```
@@ -93,6 +93,7 @@ All other fields have sensible defaults and are optional.
9393
```json
9494
{
9595
"contextPruning": {
96+
"mode": "cache-ttl",
9697
"keepLastAssistants": 3,
9798
"softTrimRatio": 0.25,
9899
"hardClearRatio": 0.5,
@@ -112,7 +113,7 @@ All other fields have sensible defaults and are optional.
112113

113114
| Field | Default | Description |
114115
|-------|---------|-------------|
115-
| `mode` | *(unset — pruning active)* | Set to `"off"` to disable pruning entirely. |
116+
| `mode` | *(unset — pruning disabled)* | Set to `"cache-ttl"` to enable pruning. Omit or leave empty to keep pruning off. |
116117
| `keepLastAssistants` | `3` | Number of recent assistant turns to protect from pruning. |
117118
| `softTrimRatio` | `0.25` | Trigger soft trim when context fills this fraction of the context window. |
118119
| `hardClearRatio` | `0.5` | Trigger hard clear when context fills this fraction after soft trim. |
@@ -127,12 +128,12 @@ All other fields have sensible defaults and are optional.
127128

128129
## Configuration Examples
129130

130-
### Disable pruning entirely
131+
### Enable pruning (minimum config)
131132

132133
```json
133134
{
134135
"contextPruning": {
135-
"mode": "off"
136+
"mode": "cache-ttl"
136137
}
137138
}
138139
```
@@ -144,6 +145,7 @@ Trigger earlier and keep less context per tool result:
144145
```json
145146
{
146147
"contextPruning": {
148+
"mode": "cache-ttl",
147149
"softTrimRatio": 0.2,
148150
"hardClearRatio": 0.4,
149151
"softTrim": {
@@ -160,6 +162,7 @@ Trigger earlier and keep less context per tool result:
160162
```json
161163
{
162164
"contextPruning": {
165+
"mode": "cache-ttl",
163166
"hardClear": {
164167
"enabled": false
165168
}
@@ -172,6 +175,7 @@ Trigger earlier and keep less context per tool result:
172175
```json
173176
{
174177
"contextPruning": {
178+
"mode": "cache-ttl",
175179
"hardClear": {
176180
"placeholder": "[Tool output removed to save context]"
177181
}
@@ -217,7 +221,7 @@ Once the consolidation pipeline has promoted a body of knowledge to L0 (via drea
217221

218222
**Pruning never triggers**
219223

220-
Confirm that `mode` is not set to `"off"`. Also confirm that `contextWindow` is set on the agent — pruning needs a token count to calculate ratios.
224+
Confirm that `mode` is set to `"cache-ttl"` — pruning is opt-in and disabled by default. Also confirm that `contextWindow` is set on the agent — pruning needs a token count to calculate ratios.
221225

222226
**Agent re-runs tools unexpectedly**
223227

@@ -227,7 +231,7 @@ Hard clear removes tool result content entirely. If the agent needs that content
227231

228232
Increase `softTrim.headChars` and `softTrim.tailChars`, or raise `softTrim.maxChars` so fewer results are eligible for trimming.
229233

230-
**Context still overflows despite pruning**
234+
**Context still overflows despite pruning being enabled**
231235

232236
Pruning only acts on tool results. If long user messages or system prompt components dominate the context, pruning will not help. Consider [session compaction](../core-concepts/sessions-and-history.md) or reduce the system prompt size.
233237

0 commit comments

Comments
 (0)