mantle

Imported from anasgets111/mantle (AGENTS.md). Install upstream with npx skills add anasgets111/mantle. Copyright stays with the author.

Mantle

Rust engine that runs desktop shells declared in Lua. It ships no shell; share/starter/shell.lua is a minimal config. Engine code, tests and comments never cite or depend on a user config, and a feature missing from one is not an engine gap. Tests use self-contained fixtures.

Code is the source of truth. Docs follow it: where a doc disagrees, fix the doc. ADRs are history, cited only as the why behind behavior the code confirms.

Map

Commands

Checks by change

Run the rows that match the change; combine rows across categories. Always run git diff --check (and git diff --cached --check for staged edits). Prose alone never needs the full suite.

With staged and unstaged edits both present, just check sets tracked unstaged edits aside (untracked files stay). To check the working tree, run just fmt-check test lint rustdoc lua types. Report failed or unavailable checks; the pre-commit hook does not replace them.

Ponytail mode

• Diffs. Delete dead, redundant and duplicated code; add lines only when nothing else works. The smallest diff in the wrong place is a second bug.
• Root cause. Fix the cause, not the symptom. Grep every caller and fix the shared function once.
• Boring. No new abstractions, dependencies or boilerplate unless required. Between similar approaches, take the edge-case-correct one.
• Ceilings. Mark a deliberate limit with a ponytail: comment naming its ceiling and upgrade path.
• Tests. Cover changed behavior with a runnable check, extending an existing test where possible. Choose coverage by risk, not line count. Prose and mechanical edits need none.
• Full effort. Validate affected trust boundaries, data integrity, security and accessibility. Calibrate hardware measurements when the change depends on them.
• Domains. One domain per file; split out a clear second one at any size, like check, install and aur in updates/pacman/. Past ~700 production lines, review the boundaries.
• Communication. Concise, direct, organized: lead with the answer, bullets for parallel points, tables for comparisons. Detail only when asked or needed for a decision, risk or blocker.
• Writing. Apply unslop everywhere; prefer numbers to adjectives. Comments explain non-obvious decisions or constraints, never narrate code. Commits state what changed and why.
• ADRs. Append one to DECISIONS.md (next number) when a choice is hard to reverse, surprising without context, and a real trade-off. Routine choices need none.
• Changelog. Every user-facing Lua API or CLI change adds a line under ## Unreleased in docs/changelog.md, in the same commit.

Trace the affected flow before writing code, then take the first option that applies:

1. Not needed for the task: omit it.
2. The codebase has it: reuse it.
3. std, the platform or an installed crate covers it: use it.
4. Otherwise write the minimum clear code that handles the required cases.

Generated files

Never hand-edit generated output: change its source, run just stubs, commit both. The the_generated_* golden tests use shared::check_generated, which rewrites with UPDATE_STUBS set and otherwise fails on a stale file.

renderer/build.rs derives config-check samples from shared/src/schema/ into Cargo's OUT_DIR. They are embedded in the renderer, never checked in or touched by just stubs.

Logging

• Use error!, warn!, notice!, info!, debug! from shared, imported by path (use shared::warn;). The macro adds timestamp, level and subsystem; never repeat the subsystem.
• notice!: start, reload, respawn, stop. info!: state changes, never setup (ADR-0251).
• eprintln! (shared's non-panicking override) only for CLI output before shared::log::init.
• MANTLE_LOG takes filters like debug, warn,tray=debug, network=off (ADR-0229).

Testing

• Tests live beside the code in #[cfg(test)] mod tests; shared/tests is the only exception.
• Never hardcode /sys or /proc: readers take sys_root/proc_root; tests pass a tempdir.
• D-Bus tests use p2p_pair() from supervisor/src/capabilities/test_support.rs, or private_bus() there when they need NameOwnerChanged; never the session or system bus.
• Docs Lua blocks run per their fence tags; lua,shot blocks must match their images in docs/images/. Rules: docs/development/documenting.md.

Skills

This file owns repository rules and check selection; skills own task workflows. They live in .agents/skills/ (symlinked as .claude/skills, .gemini/skills): implement, tdd, diagnosing-bugs, mantle-review, domain-modeling (ADRs, CONTEXT.md), grill-with-docs, grill-me, project-design, unslop. architecture-review runs only when invoked by name.