Imported from XAIHT/Tlamatini (.gemini/skills/tlamatini-self-modify-inclusion/SKILL.md). Install upstream with npx skills add XAIHT/Tlamatini --skill tlamatini-self-modify-inclusion. Copyright stays with the author.

Tlamatini — Self-Modify Inclusion Sweep

Audience: Claude Code working ON the Tlamatini codebase for Angela. Goal: guarantee the source snapshot a self-able-modify build ships (TlamatiniSourceCode/, generated by copy_source_assets.py) carries everything a rebuild needs — so a running Tlamatini can read → modify → regenerate her own Tlamatini.exe without missing the minimal thing — while staying lean (media/secrets out) and safe (no leaked keys).

This is the twin of tlamatini-self-update-inclusion. That one guards the runnable release (what users download). This one guards the SOURCE tree Tlamatini carries of herself. They overlap on one fact: a rebuild from the snapshot must be able to re-run the same build.py — so every input build.py consumes must survive the snapshot.

The acid test (the whole job in one sentence)

Can cd <install>/TlamatiniSourceCode && python build.py --self-modify succeed using only the snapshot plus the documented restore steps? If yes, the snapshot is complete.

The file this skill owns

copy_source_assets.py (repo root) — generates the snapshot. The following rules decide what ships:

It also writes _SOURCE_SNAPSHOT_MANIFEST.json (counts/restore list) and _REBUILD_INSTRUCTIONS.md (the restore + rebuild runbook). The walk is generic — any new .py/.js/.css/.yaml/.pmt/... ships automatically. The danger is the exclusions wrongly dropping a rebuild input, an omitted binary missing from the restore manifest, a new always-present capability file not in REQUIRED_SNAPSHOT_FILES, or a secret leaking.

The FIVE invariants

Invariant 1 — INCLUDE: every rebuild SOURCE input survives

Every file build.py reads to build (the build scripts, requirements.txt, all --add-data source trees, optional/required_file_copies, optional_dir_copies sources, support_files, the icon/wav/svg, every agent template, every SKILL.md, prompt.pmt, Tlamatini.md, agentic_skill.md, monitoring-prompt.pmt) must appear in the snapshot — or be in RESTORE_FROM_INSTALL. A source file dropped by an exclusion rule = a rebuild that fails or degrades.

Invariant 2 — OMIT-LEAN, but RESTORE what the build needs

Heavy media, dev trees, regenerable state and secrets stay out. Measure the actual snapshot; do not impose an obsolete ~10 MB target or drop required vendor assets. But anything omitted that the build genuinely consumes must be in RESTORE_FROM_INSTALL (restored from the install) or covered by a regeneration step in _REBUILD_INSTRUCTIONS.md (e.g. collectstatic for staticfiles). Optional inputs (the images gallery) may degrade gracefully — decide per asset whether degradation is acceptable or it needs a restore entry.

Invariant 3 — REDACT: no live secret survives

config.json and every agent config.yaml are scrubbed to <KEY goes here> placeholders; data.keys is excluded outright. The snapshot must contain zero live keys.

Invariant 4 — COMPLETENESS: critical files are guaranteed, not incidental

REQUIRED_SNAPSHOT_FILES raises if a build-/run-critical source is missing. When you add a new always-present capability (a new build script, a new identity file, a flagship new agent), add its canonical file here so a future careless exclusion can't silently drop it.

Invariant 5 — REBUILD COHERENCE: the manifest + instructions are true

_SOURCE_SNAPSHOT_MANIFEST.json and _REBUILD_INSTRUCTIONS.md exist, errors == [], and the restore steps name real omitted binaries with correct install-relative sources.

THE SWEEP — run this every time

Step 0 — run the deterministic checker (does the heavy lifting)

python .claude/skills/tlamatini-self-modify-inclusion/scripts/sweep_self_modify.py
# add --keep to retain the unique Temp/_self_modify_sweep_<id> printed by the checker

It actually generates a snapshot into Temp/ and verifies: it builds error-free with all REQUIRED_SNAPSHOT_FILES; every resolvable build.py input is carried or restorable (distinguishing source-drop FINDINGS from intentionally-omitted media/regenerable NOTES); no live secret survives (re-running copy_source_assets' own redaction logic on the OUTPUT + a config-file value scan); the restore manifest + instructions exist and name real binaries; and no source-like extension is in the exclude set. Exit code = findings (0 == clean). Fix every [FINDING]; read every [note] and confirm the degradation/regeneration is intended.

Step 1 — diff since the last release and classify new paths

git diff --name-status "$(git describe --tags --abbrev=0 --match 'v[0-9]*')"..HEAD
# brand-new TOP-LEVEL repo entries — the highest risk for a wrongly-excluded rebuild input
git diff --name-status "$(git describe --tags --abbrev=0 --match 'v[0-9]*')"..HEAD \
  | awk '$1=="A"{print $2}' | awk -F/ '{print $1}' | sort -u

For each new path ask the taxonomy question below. New .py/.js/.css/.yaml/.pmt/SKILL.md inside already-walked trees auto-ship (note, no action). The risks are: a new binary build input, a new excluded dir/ext/name that hides source, a new secret-bearing config file, or a new always-present file that belongs in REQUIRED_SNAPSHOT_FILES.

Step 2 — the judgment passes the script can't fully make

# (a) New binary build inputs the build reads (icons/fonts/wav/jar/etc.) that EXCLUDED_EXTENSIONS would drop
grep -nE "--add-data=|--icon|optional_dir_copies|required_file_copies|support_files" build.py | grep -iE "\.(ico|wav|svg|png|jpg|ttf|otf|jar|dll|bin|dat)"
# (b) New config files that may carry secrets but AREN'T covered by _wants_redaction()
grep -rilE "api[_-]?key|token|secret|password|client_secret" Tlamatini --include=*.json --include=*.yaml --include=*.yml \
  | grep -viE "/agents/.*/config.yaml$|agent/config.json$"
# (c) New dependency / runtime added (cross-check the self-update skill too)
git diff "$(git describe --tags --abbrev=0)"..HEAD -- requirements.txt

• (a) Any binary the build needs and the snapshot drops → add to RESTORE_FROM_INSTALL (omit + restore) or to the KEEP exceptions (if small + truly source-required, like the .ico/.wav/.svg already are).
• (b) Any NEW config file that can hold a live key → extend _wants_redaction() to scrub it (and confirm Step 0's redaction check then covers it), or exclude it by name.
• (c) A new dep doesn't affect the snapshot directly (it ships requirements.txt), but the rebuild pip installs it — make sure requirements.txt is current (the self-UPDATE skill owns the bundled side).

v1.48.14 External-MCP gate: the snapshot must carry agent/runtime_provisioner.py, agent/external_mcp_defaults.py, and the manager/build/secret-regeneration source, but must not copy the downloaded %LOCALAPPDATA%\Tlamatini\runtimes tree or persistent Memory graph. Treat external_mcps.json as gitignored user state: the snapshot resets it to an empty mcpServers/active document; startup seeds defaults. The public build receives inactive maintained defaults, never the keyed developer catalog. Verify REQUIRED_SNAPSHOT_FILES, _wants_redaction(), and the generated rebuild instructions agree.

v1.48.17 source-coherence gate: the snapshot must carry Grepper's encoding-safe source, agent_verdict.py, services/agent_contracts.py, Kuberneter, and their regression tests, including test_grepper_encodings.py, test_status_vocabulary.py, and test_preserved_user_state.py. The status vocabulary must remain defined once in agent_verdict.py; do not copy its sets into a snapshot helper. Confirm the generated snapshot preserves returncode/success/semantic-status fields and the updater's Uninstaller.exe rule without copying local runtime state or keyed catalogs.

v1.50.0 release source-coherence gate: the snapshot must carry the complete NetSpeed-Calculator source/config/wiring/tests and migrations 0195-0197, sqlite_copy.py plus its WAL backup/swap tests, Googler's structured-dork and two-tier plain-HTTP-first resilience source/config, test_googler_dorks.py, and the optional visible dork-hunt harness, migration 0194's Deep Internet Research prompt, and the adding_external_mcp skill tree. It must also carry the private-builder source that performs contact synchronization, but it must never copy contacts.json, contacts.private.json, a frozen-install contact book, or live External-MCP secrets. Derive current agent/tool/migration counts from the generated snapshot rather than copying historical prose counts.

PDF and update-helper carriage gate (2026-09-16)

Keep the complete Tlamatini/agent/static/agent/vendor/pdfjs/ tree, including build/pdf.mjs, build/pdf.worker.mjs, fonts, character maps, WASM decoders and licenses. The global build directory exclusion requires the exact KEEP_DIR_PATHS exception; file KEEP rules alone cannot defeat directory pruning. PDF backend/frontend files, pyinstaller_hooks/hook-pymupdf.py, the vendoring script and representative binary assets belong in REQUIRED_SNAPSHOT_FILES.

The snapshot must also include agent/sqlite_copy.py, apply_update.ps1 and preserved_user_state.json. The build carries the same SQLite helper as a standalone install-root script for the external updater. Snapshot generation errors and recorded copy failures must abort the build; never fall back to a stale static source tree. Generated rebuild instructions must require an explicit TLAMATINI_VERSION, since snapshots omit Git history and generated version files.

Step 3 — fix every finding, re-run Step 0 until clean, eyeball the notes.

Asset taxonomy — type → ship in snapshot? → action

The single most dangerous omissions: a source file hidden by an over-broad exclusion (Step 0 flags it as a source-drop FINDING) and a new secret-bearing config that _wants_redaction() doesn't cover (Step 2b — the raw scan in Step 0 catches obvious key shapes, but a novel config path needs the redaction rule extended).

Where to make each fix (copy_source_assets.py)

• A source file got excluded → narrow the offending rule in EXCLUDED_EXTENSIONS / EXCLUDED_FILE_NAMES / EXCLUDED_FILE_GLOBS / EXCLUDED_DIR_NAMES, or add a KEEP carve-out.
• An omitted binary the build needs → add "snapshot/rel/path": "install/rel/source" to RESTORE_FROM_INSTALL (it auto-renders into _REBUILD_INSTRUCTIONS.md).
• Guarantee a critical file → add its snapshot-relative path to REQUIRED_SNAPSHOT_FILES.
• A new secret-bearing config → extend _wants_redaction() to return 'json'/'yaml' for it (and add the key suffix to _SECRET_KEY_RE if it's a novel secret-key name).
• A new state/output dir leaking in → add its name to EXCLUDED_DIR_NAMES.

Done criteria (all must hold)

1. sweep_self_modify.py exits clean (no [FINDING]); every [note] is reviewed + intended.
2. Every new top-level repo path from the since-last-tag diff is classified and handled.
3. Snapshot generation completes error-free with every REQUIRED_SNAPSHOT_FILES entry; separately state whether an actual rebuild was run.
4. Every build.py SOURCE input is in the snapshot or in RESTORE_FROM_INSTALL.
5. Zero live secrets in the snapshot (redaction check + value scan pass).
6. The manifest + _REBUILD_INSTRUCTIONS.md are accurate; restore targets are real.
7. python -m ruff check copy_source_assets.py is clean.
8. (Ideal) you eyeballed a --keep snapshot and spot-confirmed the newest feature's source files are physically present.

Complete carrier/redaction gate (2026-09-16)

• validate_snapshot_carriage() checks EVERY source file in the shared runtime SOURCE_TREES and ROOT_SOURCES, not just representative canaries. Each must match source bytes (except intentionally sanitized configuration), or have an explicit RESTORE_FROM_INSTALL mapping. Collected static is regenerated.
• Keep all tracked PDFer agents/pdfer/_art/** ornaments; they are small rendering inputs, unlike the optional agent/images/ gallery. Keep all local frontend vendor files/fonts/licenses and exact vendor build/dist directory exceptions.
• Require installer/uninstaller, public/private wrappers, integrity helper, External MCP defaults/provisioner, and both inclusion skills/checkers. Keep the .claude and .gemini copies synchronized.
• Malformed JSON/YAML or unavailable PyYAML must abort redaction, not return raw content. Parse YAML structures so block scalars/flow mappings/aliases cannot bypass a line-based scrubber. Exceptions and audit reports must not print keys' values, including token prefixes. Unknown new secret-bearing configs still require human classification; shape scans do not prove universal secrecy.
• Custom destinations must be dedicated repository descendants. An existing nonempty destination requires a snapshot manifest before replacement. Reject linked source inputs. The emitted manifest omits developer absolute paths.
• The file-only checker creates a fresh unique scratch directory. A CLEAN result proves its stated source guards, NOT a successful frozen rebuild. Honor any no-tests/no-build restriction and do not silently expand this sweep.

Companion references

• tlamatini-self-update-inclusion — the sibling skill guarding the runnable release (build.py carriers + the update swap). Run BOTH after any feature: one proves users can receive the feature, this one proves Tlamatini can rebuild herself with it.
• docs/claude/architecture.md → Self-Knowledge & Self-Modification and docs/claude/gotchas.md → Building & Packaging for the --self-modify flag mechanics.
• VERSIONING.md — use Git tags in the repository; a Git-free snapshot requires an explicit TLAMATINI_VERSION.