Skip to content

Commit 170cc53

Browse files
committed
docs(agent): replace em-dash separators with colon-space
Pre-existing bullets and tier titles used ' -- ' as a separator. Convert to ': ' to match the project style guide and remove a strong AI-output signature. Signed-off-by: Huang Rui <vowstar@gmail.com>
1 parent 97fd08b commit 170cc53

1 file changed

Lines changed: 45 additions & 45 deletions

File tree

doc/en/agent.typ

Lines changed: 45 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -95,29 +95,29 @@ The following commands are available during an interactive session:
9595
<agent-keyboard>
9696
Editing and navigation in the prompt:
9797

98-
- *Left/Right*, *Ctrl+A/E* -- Move cursor / jump to start or end of line
99-
- *Up/Down* -- Browse prompt history
100-
- *Ctrl+K*, *Ctrl+U*, *Ctrl+W* -- Delete to end of line / start of line / previous word
101-
- *Backspace* -- Delete character before cursor (CJK/emoji aware)
102-
- *Ctrl+\_* -- Undo the last edit
103-
- *`\` + Enter* -- Continue on next line; multi-line paste is preserved as one input
98+
- *Left/Right*, *Ctrl+A/E*: Move cursor / jump to start or end of line
99+
- *Up/Down*: Browse prompt history
100+
- *Ctrl+K*, *Ctrl+U*, *Ctrl+W*: Delete to end of line / start of line / previous word
101+
- *Backspace*: Delete character before cursor (CJK/emoji aware)
102+
- *Ctrl+\_*: Undo the last edit
103+
- *`\` + Enter*: Continue on next line; multi-line paste is preserved as one input
104104

105105
External editor and search:
106106

107-
- *Ctrl+X Ctrl+E* or *Ctrl+G* -- Edit current input in `$EDITOR`
108-
- *Ctrl+R* -- Reverse-i-search through prompt history
107+
- *Ctrl+X Ctrl+E* or *Ctrl+G*: Edit current input in `$EDITOR`
108+
- *Ctrl+R*: Reverse-i-search through prompt history
109109

110110
View and selection:
111111

112-
- *Ctrl+T* -- Toggle TODO list visibility
113-
- *Ctrl+L* -- Force a full screen repaint
114-
- *Mouse drag* -- Select and auto-copy to clipboard (OSC 52)
115-
- *Shift + drag* -- Native terminal selection (fallback)
112+
- *Ctrl+T*: Toggle TODO list visibility
113+
- *Ctrl+L*: Force a full screen repaint
114+
- *Mouse drag*: Select and auto-copy to clipboard (OSC 52)
115+
- *Shift + drag*: Native terminal selection (fallback)
116116

117117
Completion and interrupt:
118118

119-
- *`@<name>`* -- Fuzzy-complete a project file path
120-
- *ESC* -- Abort the current operation
119+
- *`@<name>`*: Fuzzy-complete a project file path
120+
- *ESC*: Abort the current operation
121121

122122
While the agent is executing, you can keep typing. Press *Enter* to submit; the
123123
agent consumes queued requests at the start of the next iteration. Pressing
@@ -128,30 +128,30 @@ calls; conversation history is preserved.
128128
<agent-decision-flow>
129129
The agent follows a four-tier decision flow for every request:
130130

131-
+ *Tier 1 -- Skills*: Search for matching user-defined skills via `skill_find`.
131+
+ *Tier 1: Skills*: Search for matching user-defined skills via `skill_find`.
132132
If a skill matches, read and follow its instructions.
133-
+ *Tier 2 -- SoC Infrastructure*: If the request involves clock tree, reset
133+
+ *Tier 2: SoC Infrastructure*: If the request involves clock tree, reset
134134
network, power sequencing, or FSM generation, the agent queries built-in
135135
documentation (`query_docs`) for the YAML format, writes a `.soc_net` file,
136136
and calls `generate_verilog` to produce production-grade RTL. The agent never
137137
writes clock/reset/power/FSM Verilog by hand.
138-
+ *Tier 3 -- Plan*: For tasks requiring 3+ steps, decompose into a TODO
138+
+ *Tier 3: Plan*: For tasks requiring 3+ steps, decompose into a TODO
139139
checklist before execution.
140-
+ *Tier 4 -- Execute*: Use file, shell, generation, or other tools directly.
140+
+ *Tier 4: Execute*: Use file, shell, generation, or other tools directly.
141141

142142
== SoC INFRASTRUCTURE
143143
<agent-soc-infrastructure>
144144
The `generate_verilog` tool produces production RTL from `.soc_net` YAML files
145145
with four primitive generators:
146146

147-
- *Clock* -- ICG gating, static/dynamic/auto dividers, glitch-free MUX, STA
147+
- *Clock*: ICG gating, static/dynamic/auto dividers, glitch-free MUX, STA
148148
guide buffers, test enable bypass
149-
- *Reset* -- ARSR synchronizers (async assert / sync release), multi-source
149+
- *Reset*: ARSR synchronizers (async assert / sync release), multi-source
150150
matrices, reset reason recording
151-
- *Power* -- 8-state FSM per domain
151+
- *Power*: 8-state FSM per domain
152152
(OFF→WAIT\_DEP→TURN\_ON→CLK\_ON→ON→RST\_ASSERT→TURN\_OFF), hard/soft
153153
dependencies, fault recovery
154-
- *FSM* -- Table-mode (Moore/Mealy) and microcode-mode, binary/onehot/gray
154+
- *FSM*: Table-mode (Moore/Mealy) and microcode-mode, binary/onehot/gray
155155
encoding
156156

157157
The agent detects SoC infrastructure requests by keyword (clock, reset, power,
@@ -161,26 +161,26 @@ FSM, etc.) and routes them through Tier 2 automatically.
161161
<agent-capabilities>
162162
The agent provides the following tools through natural language:
163163

164-
- *Project* -- `project_list`, `project_show`, `project_create`
165-
- *Module* -- `module_list`, `module_show`, `module_import`, `module_bus_add`
166-
- *Bus* -- `bus_list`, `bus_show`, `bus_import` (AXI, APB, Wishbone, etc.)
167-
- *Generation* -- `generate_verilog` (RTL from `.soc_net`), `generate_template`
164+
- *Project*: `project_list`, `project_show`, `project_create`
165+
- *Module*: `module_list`, `module_show`, `module_import`, `module_bus_add`
166+
- *Bus*: `bus_list`, `bus_show`, `bus_import` (AXI, APB, Wishbone, etc.)
167+
- *Generation*: `generate_verilog` (RTL from `.soc_net`), `generate_template`
168168
(Jinja2 rendering)
169-
- *Files* -- `read_file`, `list_files`, `write_file`, `edit_file`; `path_context`
169+
- *Files*: `read_file`, `list_files`, `write_file`, `edit_file`; `path_context`
170170
reports and adjusts allowed write directories
171-
- *Shell* -- `bash` with timeout, `bash_manage` for background processes
172-
- *Documentation* -- `query_docs` by topic (about, commands, config, bus, clock,
171+
- *Shell*: `bash` with timeout, `bash_manage` for background processes
172+
- *Documentation*: `query_docs` by topic (about, commands, config, bus, clock,
173173
fsm, logic, netlist, power, reset, template, validation, overview, ...)
174-
- *Memory* -- `memory_read`, `memory_write` for persistent notes across sessions
175-
- *Todo* -- `todo_list`, `todo_add`, `todo_update`, `todo_delete` for multi-step
174+
- *Memory*: `memory_read`, `memory_write` for persistent notes across sessions
175+
- *Todo*: `todo_list`, `todo_add`, `todo_update`, `todo_delete` for multi-step
176176
workflows
177-
- *Skills* -- `skill_find`, `skill_create` for user-defined prompt templates
177+
- *Skills*: `skill_find`, `skill_create` for user-defined prompt templates
178178
resolved across four layers (`$QSOC_HOME/skills`, `<project>/.qsoc/skills`,
179179
`~/.config/qsoc/skills`, and a platform-native system skills dir), plus
180180
any directory listed in `QSOC_SKILLS_PATH`; see @agent-skills for the
181181
SKILL.md format and @config-files for the full layout
182-
- *LSP* -- `lsp` for language server diagnostics and symbol lookup
183-
- *Web* -- `web_fetch` for URL content, `web_search` via SearXNG (when configured)
182+
- *LSP*: `lsp` for language server diagnostics and symbol lookup
183+
- *Web*: `web_fetch` for URL content, `web_search` via SearXNG (when configured)
184184

185185
== SKILLS
186186
<agent-skills>
@@ -277,11 +277,11 @@ output is displayed in dim text.
277277
<agent-context-compaction>
278278
Long conversations are managed by a three-layer compaction system:
279279

280-
+ *Tool Output Pruning* (60% threshold) -- Old tool outputs are replaced with
280+
+ *Tool Output Pruning* (60% threshold): Old tool outputs are replaced with
281281
`[output pruned]`. Zero LLM calls.
282-
+ *LLM Compaction* (80% threshold) -- Older messages are summarized by the LLM,
282+
+ *LLM Compaction* (80% threshold): Older messages are summarized by the LLM,
283283
preserving technical details (file paths, decisions, errors).
284-
+ *Auto-Continue* -- After compaction during streaming, the agent automatically
284+
+ *Auto-Continue*: After compaction during streaming, the agent automatically
285285
resumes the current task.
286286

287287
Use `/compact` to trigger compaction manually, and `/context` to inspect the
@@ -291,12 +291,12 @@ per-category token breakdown.
291291
<agent-system-prompt>
292292
On every turn, the system prompt is composed from:
293293

294-
- *Modular sections* -- built-in role, decision flow, and tool usage guidance
295-
- *Project instructions* -- `AGENTS.md` and `AGENTS.local.md` in the project
294+
- *Modular sections*: built-in role, decision flow, and tool usage guidance
295+
- *Project instructions*: `AGENTS.md` and `AGENTS.local.md` in the project
296296
directory, injected verbatim
297-
- *Memory* -- entries from the auto-memory store (see `memory_read` /
297+
- *Memory*: entries from the auto-memory store (see `memory_read` /
298298
`memory_write`), capped by `agent.memory_max_chars`
299-
- *Skill listing* -- names and descriptions of installed skills so the agent
299+
- *Skill listing*: names and descriptions of installed skills so the agent
300300
can route to them via `skill_find`
301301

302302
Set `agent.system_prompt` in the config to replace the modular base with a
@@ -407,12 +407,12 @@ The agent uses a read-unrestricted, write-restricted permission model:
407407
Each session is persisted as `.qsoc/sessions/<id>.jsonl` under the project
408408
directory, one JSON event per line (messages plus metadata). This enables:
409409

410-
- `qsoc agent --continue` -- resume the most recent session
411-
- `qsoc agent --resume [id]` -- pick a session from a list, or load one by id /
410+
- `qsoc agent --continue`: resume the most recent session
411+
- `qsoc agent --resume [id]`: pick a session from a list, or load one by id /
412412
unique prefix
413-
- `/branch [name]` -- fork the current session into a new id, preserving the
413+
- `/branch [name]`: fork the current session into a new id, preserving the
414414
original
415-
- `/rename <title>` -- set a human-readable title shown by the resume picker
415+
- `/rename <title>`: set a human-readable title shown by the resume picker
416416

417417
== USAGE EXAMPLES
418418
<agent-examples>

0 commit comments

Comments
 (0)