Skip to content

Commit 662797e

Browse files
mios-devclaude
mios-dev
and
claude
committed
delete English-prose research docs + ship mios-docs-index (unified)
Operator-flagged 2026-05-18 multi-step: 1. "NOO!!! HARDCODED ENGLISH!!!!" -- my multi-agent-architecture.md + native-os-agent-patterns.md were 250+ lines of English prose each, registered into the MiOS Documentation OWUI knowledge collection where they would auto-RAG-inject English chunks into every non-English chat. Contamination by construction. 2. "clear caches and all rag temp etc-etc--EVERYTHING CLEANSLATE AND SANITIZED" -- full wipe. 3. ".md files should ALL be accessible by all agents context windows/scratchpad (GLOBAL UNIFIED)" -- unified discovery, not RAG drip. 4. Slim my SOUL.md addition (was 8+ lines of English narrative) -- replaced with a 3-line one-liner pointing at the helper. Three concrete actions in this commit: 1. DELETED both research .md files from the repo: * usr/share/mios/docs/multi-agent-architecture.md * usr/share/mios/docs/native-os-agent-patterns.md They were a mistake (English-prose contamination of a locale- mirrored agent stack). Live system + OWUI knowledge_file rows also unregistered + deleted (collection 'MiOS Documentation' went 34 -> 33 files). 2. NEW mios-docs-index shim (Day-0 image-immutable at /usr/libexec/mios/, symlinked into /usr/local/{s,}bin via tmpfiles.d -- shim count 42 -> 43). Walks 9 doc surfaces: /usr/share/mios/ai agent identities + prompts /usr/share/mios/docs FHS architecture refs /usr/share/mios/hermes/skills SKILL.md per skill /usr/share/mios/cookbooks /usr/share/mios/prompts /etc/mios/system-prompts /var/lib/mios/scratch shared mutable scratchpad /var/lib/mios/ai/scratch assistant scratchpad /var/lib/mios/compacted session digests Emits `<path> -- <one-line description>` per .md (description pulled from YAML frontmatter `description:` -> first H1 -> first non-blank line). --grep <pattern> filters. --write persists to /var/lib/mios/scratch/docs-index.md so agents can `cat` the cached index instead of re-walking the filesystem. 3. AUTO-REFRESH on hermes restart. hermes-agent.service.d/ 50-soul-sync.conf gains a second ExecStartPre: ExecStartPre=-/usr/libexec/mios/mios-docs-index --write (leading `-` makes it non-fatal -- daemon still starts if the helper fails). Live-verified: hermes restart -> 59-line index refreshed at /var/lib/mios/scratch/docs-index.md before the gateway accepts the first request. SOUL.md: replaced the 8-line "Doc discovery -- global unified .md surface (no RAG drip)" section with a 3-line "Docs" section: just the verb + filter syntax. Less English prose in the system prompt = less locale contamination. Cache wipe done too: full mios-cache-clear --all + extra /var/lib/mios/{compacted,scratch}/* + daemon state.json + launch_failures.json + container /app/backend/data/cache + vector_db. Post-state: 0 chats / messages / memory; 33 knowledge files (the FHS canonicals registered by mios-owui-apply-knowledge -- those are operator-canonical docs, not my contamination). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 6c8639b commit 662797e

6 files changed

Lines changed: 148 additions & 416 deletions

File tree

‎usr/lib/systemd/system/hermes-agent.service.d/50-soul-sync.conf‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,7 @@
1818

1919
[Service]
2020
ExecStartPre=/usr/libexec/mios/mios-hermes-soul-sync
21+
# Refresh the unified docs index at every hermes start so
22+
# /var/lib/mios/scratch/docs-index.md is current for any agent
23+
# that wants to `cat` it without re-running mios-docs-index.
24+
ExecStartPre=-/usr/libexec/mios/mios-docs-index --write

‎usr/lib/tmpfiles.d/mios-shim-links.conf‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,5 @@ L+ /usr/local/bin/mios-knowledge-add - - - - /usr/libexec/mios/mios-knowle
9595
L+ /usr/local/sbin/mios-knowledge-add - - - - /usr/libexec/mios/mios-knowledge-add
9696
L+ /usr/local/bin/mios-gpu-passthrough - - - - /usr/libexec/mios/mios-gpu-passthrough
9797
L+ /usr/local/sbin/mios-gpu-passthrough - - - - /usr/libexec/mios/mios-gpu-passthrough
98+
L+ /usr/local/bin/mios-docs-index - - - - /usr/libexec/mios/mios-docs-index
99+
L+ /usr/local/sbin/mios-docs-index - - - - /usr/libexec/mios/mios-docs-index

‎usr/libexec/mios/mios-docs-index‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
#!/bin/bash
2+
# /usr/libexec/mios/mios-docs-index [--grep <pattern>] [--write]
3+
#
4+
# Print a unified index of every .md doc on the MiOS host so agents
5+
# (Hermes, MiOS-Agent, future OpenCode, MCP clients) can DISCOVER
6+
# what's available, then `cat` the specific file on demand. Per
7+
# operator directive 2026-05-18: ".md files should ALL be accessible
8+
# by all agents context windows/scratchpad (GLOBAL UNIFIED)".
9+
#
10+
# Doc surfaces scanned (all Day-0 image-immutable except scratch):
11+
# /usr/share/mios/ai/ agent identities + system prompts
12+
# /usr/share/mios/docs/ FHS architecture docs
13+
# /usr/share/mios/hermes/skills/<skill>/SKILL.md
14+
# /usr/share/mios/cookbooks/ operator workflows
15+
# /usr/share/mios/prompts/ meta-prompts
16+
# /etc/mios/system-prompts/ operator overrides (mutable)
17+
# /var/lib/mios/scratch/ shared mutable scratchpad (agent notes)
18+
# /var/lib/mios/ai/scratch/ assistant-side scratchpad
19+
# /var/lib/mios/compacted/ session digests (mios-compact output)
20+
#
21+
# Rationale (vs RAG auto-injection): operator-flagged 2026-05-18
22+
# "NOO!!! HARDCODED ENGLISH!!!" -- English-prose docs in the RAG
23+
# collection got chunked + injected on every chat regardless of
24+
# the operator's actual locale, contaminating non-English replies.
25+
# Filesystem-discoverable + on-demand `cat` keeps the docs available
26+
# without that drip. Agents read the index, see one-line summaries,
27+
# decide what (if anything) to load into context.
28+
#
29+
# Usage:
30+
# mios-docs-index print full index to stdout
31+
# mios-docs-index --grep wsl filter to lines matching pattern
32+
# mios-docs-index --write also persist to
33+
# /var/lib/mios/scratch/docs-index.md
34+
# (so agents can `cat` the index
35+
# without re-running this script)
36+
#
37+
# Output: one row per .md, "<path> <one-line-description>" where
38+
# the description is the YAML-frontmatter `description:` if present,
39+
# else the first H1 line, else the first 80 chars of the first
40+
# non-blank line.
41+
42+
set -uo pipefail
43+
44+
PATTERN=""
45+
WRITE=0
46+
INDEX_OUT="/var/lib/mios/scratch/docs-index.md"
47+
48+
while [ "$#" -gt 0 ]; do
49+
case "$1" in
50+
--grep) PATTERN="$2"; shift 2 ;;
51+
--write) WRITE=1; shift ;;
52+
-h|--help)
53+
sed -n '2,40p' "$0" | sed 's/^# \?//'
54+
exit 0 ;;
55+
*) echo "mios-docs-index: unknown arg: $1" >&2; exit 64 ;;
56+
esac
57+
done
58+
59+
SCAN_ROOTS=(
60+
"/usr/share/mios/ai"
61+
"/usr/share/mios/docs"
62+
"/usr/share/mios/hermes/skills"
63+
"/usr/share/mios/cookbooks"
64+
"/usr/share/mios/prompts"
65+
"/etc/mios/system-prompts"
66+
"/var/lib/mios/scratch"
67+
"/var/lib/mios/ai/scratch"
68+
"/var/lib/mios/compacted"
69+
)
70+
71+
# Pull a one-line description from a .md file. Frontmatter description:
72+
# wins; else first H1; else first non-blank line.
73+
_describe() {
74+
local f="$1" line=""
75+
# 1. YAML frontmatter description: (handles single AND multi-line)
76+
line="$(awk '
77+
BEGIN { in_fm=0; n=0 }
78+
NR==1 && /^---[[:space:]]*$/ { in_fm=1; next }
79+
in_fm && /^---[[:space:]]*$/ { exit }
80+
in_fm && /^description:/ {
81+
sub(/^description:[[:space:]]*/, "")
82+
sub(/^["\x27]/, ""); sub(/["\x27][[:space:]]*$/, "")
83+
if (length($0) > 0) { print; exit }
84+
next
85+
}
86+
' "$f" 2>/dev/null | head -1)"
87+
if [ -n "$line" ]; then echo "${line:0:180}"; return; fi
88+
# 2. First H1
89+
line="$(grep -m1 '^# ' "$f" 2>/dev/null | sed 's/^#\s*//')"
90+
if [ -n "$line" ]; then echo "${line:0:180}"; return; fi
91+
# 3. First non-blank, non-frontmatter, non-comment line
92+
line="$(awk '
93+
BEGIN { in_fm=0 }
94+
NR==1 && /^---[[:space:]]*$/ { in_fm=1; next }
95+
in_fm && /^---[[:space:]]*$/ { in_fm=0; next }
96+
in_fm { next }
97+
/^[[:space:]]*$/ { next }
98+
/^[[:space:]]*<!--/ { next }
99+
{ print; exit }
100+
' "$f" 2>/dev/null)"
101+
echo "${line:0:180}"
102+
}
103+
104+
emit_index() {
105+
echo "# MiOS unified doc index"
106+
echo "_auto-generated by mios-docs-index_"
107+
echo
108+
echo "Format: \`<path> -- <one-line description>\`."
109+
echo
110+
for root in "${SCAN_ROOTS[@]}"; do
111+
[ -d "$root" ] || continue
112+
echo "## $root"
113+
echo
114+
# Find + sort + describe each .md
115+
while IFS= read -r f; do
116+
desc="$(_describe "$f")"
117+
# Trim path to keep lines scannable
118+
printf '%s -- %s\n' "$f" "$desc"
119+
done < <(find "$root" -type f -name '*.md' 2>/dev/null | sort)
120+
echo
121+
done
122+
}
123+
124+
if [ "$WRITE" = "1" ]; then
125+
install -d -m 0755 "$(dirname "$INDEX_OUT")"
126+
emit_index > "${INDEX_OUT}.tmp"
127+
mv -f "${INDEX_OUT}.tmp" "$INDEX_OUT"
128+
chmod 0644 "$INDEX_OUT"
129+
echo "[mios-docs-index] wrote $INDEX_OUT ($(wc -l < "$INDEX_OUT") lines)"
130+
fi
131+
132+
if [ -n "$PATTERN" ]; then
133+
emit_index | grep -E "$PATTERN" 2>/dev/null
134+
else
135+
emit_index
136+
fi

‎usr/share/mios/ai/hermes-soul.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,12 @@ State paths (read freely):
227227
saves you from re-walking the logs yourself, and surfaces nudges
228228
(a stalled task, an unverified launch, a scratchpad note flagged
229229
by another agent) you'd otherwise miss.
230+
231+
## Docs
232+
233+
`terminal: mios-docs-index` — unified index of every `.md` on disk
234+
(skills / system prompts / cookbooks / scratchpads / session
235+
digests). `--grep <pattern>` filters. Then `terminal: cat <path>`.
230236
- `/var/lib/mios/daemon/state.json` — unified daemon state
231237
(classify, refusal, cron, suggestions, launch_verifier sections)
232238

‎usr/share/mios/docs/multi-agent-architecture.md‎

Lines changed: 0 additions & 150 deletions
This file was deleted.

0 commit comments

Comments
 (0)