diff --git a/.agents/README.md b/.agents/README.md new file mode 100644 index 00000000..4df6ecd6 --- /dev/null +++ b/.agents/README.md @@ -0,0 +1,114 @@ +# Agent guidance for MeshChatX + +Notes for automated agents and for people who work like agents. +This tree is not in-app user documentation. End-user docs live under `docs/en/`. + +## Start here + +1. [overview.md](overview.md) for architecture, storage, security, env vars, and invariants. +2. [conventions/reticulum-zen.md](conventions/reticulum-zen.md) before any mesh-facing design or code. +3. [conventions/](conventions/) for the surface you are editing. +4. A [skills/](skills/) guide when the task matches that workflow. +5. [skills/no-ai-slop/SKILL.md](skills/no-ai-slop/SKILL.md) before writing or editing prose (docs, UI copy, commit messages longer than a sentence). + +Root [AGENTS.md](../AGENTS.md) points here. + +Editor rules (if present under `.cursor/rules/`): + +- Always on: MeshChatX core standards and Reticulum Zen gates +- Globs: backend, frontend, Android, tests + +## Layout + +| Path | Purpose | +| --- | --- | +| [overview.md](overview.md) | Project brief and invariants | +| [module-ownership.md](module-ownership.md) | Domain to manager / HTTP / WS / tests map | +| [conventions/reticulum-zen.md](conventions/reticulum-zen.md) | Zen of Reticulum hard gates | +| [conventions/core.md](conventions/core.md) | Always-on standards | +| [conventions/frontend.md](conventions/frontend.md) | Vue UI | +| [conventions/backend.md](conventions/backend.md) | Python / HTTP / SQLite | +| [conventions/path-jail.md](conventions/path-jail.md) | Local FS APIs: jail, symlinks, tests | +| [conventions/android.md](conventions/android.md) | Android WebView bridge | +| [conventions/tests.md](conventions/tests.md) | Test placement, oracles, verification | + +## Skills + +Each skill is `.agents/skills//SKILL.md` with YAML frontmatter (`name` matches the directory). + +### Writing + +Copied from [realrossmanngroup/no_ai_slop_writing_rules](https://github.com/realrossmanngroup/no_ai_slop_writing_rules). Load `no-ai-slop` for every prose pass. Load `rossmann-voice` only when the user asks for that voice. + +| Skill | Use when | +| --- | --- | +| [no-ai-slop](skills/no-ai-slop/SKILL.md) | Writing or editing prose. Banned patterns and WRONG/RIGHT fixes. Rules: [references/rules.md](skills/no-ai-slop/references/rules.md). | +| [rossmann-voice](skills/rossmann-voice/SKILL.md) | User asked for Louis Rossmann's voice (claim-then-proof, contractions, testable numbers). | + +### Reticulum + +Philosophy: [Zen of Reticulum](https://reticulum.network/manual/zen.html). Site: [reticulum.network](https://reticulum.network/). + +| Skill | Use when | +| --- | --- | +| [reticulum-design-gates](skills/reticulum-design-gates/SKILL.md) | Mesh design review against Zen gates | +| [reticulum-stack](skills/reticulum-stack/SKILL.md) | Identities, destination hashes, aspects, announces, paths, links | +| [reticulum-interfaces](skills/reticulum-interfaces/SKILL.md) | Interface config, RNode/TCP/AutoInterface, medium-agnostic app code | +| [rns-link-api](skills/rns-link-api/SKILL.md) | Generic RNS Link WebSocket / plugin transport | +| [lxmf-messaging](skills/lxmf-messaging/SKILL.md) | LXMF send/receive, stamps, propagation, attachments | +| [lxst-telephony](skills/lxst-telephony/SKILL.md) | LXST calls, audio WS, telephony managers | +| [rrc-relay-chat](skills/rrc-relay-chat/SKILL.md) | Relay Chat hubs, rooms, +k keys, moderation | +| [rns-filesync](skills/rns-filesync/SKILL.md) | RNS FileSync shares, announces, sync-root jail | +| [nomad-pages](skills/nomad-pages/SKILL.md) | NomadNet browser, Mesh Server page nodes, Micron | +| [privacy-mode-clearnet](skills/privacy-mode-clearnet/SKILL.md) | Privacy mode vs outbound HTTP. Mesh traffic stays up. | + +### UI and wiring + +| Skill | Use when | +| --- | --- | +| [page-toast-tests](skills/page-toast-tests/SKILL.md) | New pages, toasts, i18n, tests | +| [contribution-registries](skills/contribution-registries/SKILL.md) | Nav, tools, commands, settings search, WS event wiring | +| [vue-mega-page-split](skills/vue-mega-page-split/SKILL.md) | Extract Vue mega-pages into internal/sections/helpers | +| [meshchat-orchestration-split](skills/meshchat-orchestration-split/SKILL.md) | Extract HTTP/WS from meshchat.py, multi-file scanners | + +### Identity and data + +| Skill | Use when | +| --- | --- | +| [identity-restore](skills/identity-restore/SKILL.md) | Identity key vs database zip restore | +| [identity-switch-teardown](skills/identity-switch-teardown/SKILL.md) | Live identity switch without cross-identity leaks | +| [database-migrations-backups](skills/database-migrations-backups/SKILL.md) | Schema bumps, backups, snapshots, restore safety | +| [landlock-sqlite](skills/landlock-sqlite/SKILL.md) | Landlock + SQLite, subprocess/user-local CLI probes | + +### Security and plugins + +| Skill | Use when | +| --- | --- | +| [auth-csrf-ws-security](skills/auth-csrf-ws-security/SKILL.md) | CSRF, auth, WS mutator denylist | +| [path-jail-local-fs](skills/path-jail-local-fs/SKILL.md) | Local file browse/upload/delete path jails | +| [plugin-install-security](skills/plugin-install-security/SKILL.md) | Plugin install, RSG, permissions, integrity | + +### Platforms and boot + +| Skill | Use when | +| --- | --- | +| [deferred-network-startup](skills/deferred-network-startup/SKILL.md) | HTTP-up vs RNS-ready, status, 503s, RNS panic | +| [electron-frozen-packaging](skills/electron-frozen-packaging/SKILL.md) | Frozen desktop spawn, loading, crash recovery | +| [android-webview-bridge](skills/android-webview-bridge/SKILL.md) | Android chooser MIME, storage, WebView nav | + +### Verification + +| Skill | Use when | +| --- | --- | +| [test-loop](skills/test-loop/SKILL.md) | Focused verification without hung shells | +| [test-oracles](skills/test-oracles/SKILL.md) | Property/fuzz oracles: accept/reject, not soft fuzz | +| [exploratory-testing](skills/exploratory-testing/SKILL.md) | Adversarial exploration with hypotheses | + +## Product docs (users) + +- `docs/en/architecture.md` +- `docs/en/identity-and-security.md` +- `docs/en/getting-started.md` +- `docs/en/rns-link-api.md` +- `docs/en/platform-guides/linux-sandbox.md` +- `CONTRIBUTING.md` diff --git a/docs/agents/conventions/android.md b/.agents/conventions/android.md similarity index 100% rename from docs/agents/conventions/android.md rename to .agents/conventions/android.md diff --git a/docs/agents/conventions/backend.md b/.agents/conventions/backend.md similarity index 78% rename from docs/agents/conventions/backend.md rename to .agents/conventions/backend.md index 94914aa1..21e44b0a 100644 --- a/docs/agents/conventions/backend.md +++ b/.agents/conventions/backend.md @@ -7,7 +7,7 @@ Applies when editing `meshchatx/**/*.py`. - Thin HTTP handlers live under `meshchatx/src/backend/http/routes/`. Parse the request, call a manager or app method, map errors. Do not add new business logic in route modules. - Shared HTTP helpers: `backend/http/errors.py`, `backend/http/context.py`, `backend/http/middleware.py`, `backend/http/register.py`, `backend/http/live_names.py`. - `errors.py` and `context.py` are intentional scaffolding. Adopt `http_bad_request` / `http_unavailable` / `http_unexpected` only when a handler is already thin. Do not refactor fat handlers only to call them. -- When splitting or moving handlers among `routes/.py`, follow `docs/agents/skills/meshchat-orchestration-split/SKILL.md` and `docs/agents/module-ownership.md`. Mechanical moves only (no behaviour change in the same change). +- When splitting or moving handlers among `routes/.py`, follow `.agents/skills/meshchat-orchestration-split/SKILL.md` and `.agents/module-ownership.md`. Mechanical moves only (no behaviour change in the same change). - Multipart parsers must not assume field order. - SQLite worker connections must set `temp_store=MEMORY` in `DatabaseProvider` (Landlock-safe). - Under Landlock, memory-pressure must not force FILE temp for conversation queries. @@ -15,5 +15,5 @@ Applies when editing `meshchatx/**/*.py`. - Keep conversation list queries slim: truncate content, derive attachment flags in SQL, avoid shipping full `fields` blobs. - Identity restore validates size and empty payloads. Preserve existing identity metadata on re-import. - No backticks in code comments. Prefer plain words or quoted identifiers. -- RRC / LXMF / LXST changes: open the matching skill under `docs/agents/skills/` and run oracle-style tests when behaviour changes. -- Local filesystem browse/upload/download/delete: follow `docs/agents/conventions/path-jail.md` and `docs/agents/skills/path-jail-local-fs/SKILL.md`. +- RRC / LXMF / LXST changes: open the matching skill under `.agents/skills/` and run oracle-style tests when behaviour changes. +- Local filesystem browse/upload/download/delete: follow `.agents/conventions/path-jail.md` and `.agents/skills/path-jail-local-fs/SKILL.md`. diff --git a/.agents/conventions/core.md b/.agents/conventions/core.md new file mode 100644 index 00000000..1dd9a8fa --- /dev/null +++ b/.agents/conventions/core.md @@ -0,0 +1,22 @@ +# Core conventions + +- Read `.agents/overview.md` for layout, commands, and domain traps. +- Mesh-facing work: read `.agents/conventions/reticulum-zen.md` and run `.agents/skills/reticulum-design-gates/SKILL.md` gates first. +- Prefer `task` targets (`format`, `lint`, `test:quick`, `test:backend`, `test:frontend`). +- Minimal diffs. Match nearby style. Keep SPDX headers on new project files (`0BSD` unless file already differs). +- No emojis in repo text. No TODO/FIXME comment noise. +- No emdashes or semicolons in comments or docs you write. +- No backticks in code comments. Prefer plain words or quoted identifiers. +- Do not commit/push unless asked. +- User-visible UI strings: i18n keys. Action feedback: `ToastUtils`. +- Do not invent install/run flows when Taskfile already covers them. +- Do not create markdown docs unless asked (except agent guidance under `.agents/` when requested). +- Do not generate exploit PoCs, malware, or attack tooling. + +## Prose + +Before writing or editing prose, read `.agents/skills/no-ai-slop/SKILL.md` and self-check against `.agents/skills/no-ai-slop/references/ai-writing-detection.md`. The 24 rules are in `.agents/skills/no-ai-slop/references/rules.md`. + +Say what the thing is. Headings name the section contents. Every claim ends on a checkable detail (a path, an API, a status code, a measured quantity). Do not invent numbers, quotes, or incidents. + +Load `.agents/skills/rossmann-voice/SKILL.md` only when the user asks for that voice. Do not rewrite MeshChatX technical docs into that voice by default. diff --git a/docs/agents/conventions/frontend.md b/.agents/conventions/frontend.md similarity index 91% rename from docs/agents/conventions/frontend.md rename to .agents/conventions/frontend.md index 85b5a319..378b6f09 100644 --- a/docs/agents/conventions/frontend.md +++ b/.agents/conventions/frontend.md @@ -15,8 +15,8 @@ Applies when editing `meshchatx/src/frontend/**/*.{vue,js}`. ## Mega-page extracts -When splitting large page shells, follow `docs/agents/skills/vue-mega-page-split/SKILL.md` -and the Frontend mega-pages table in `docs/agents/module-ownership.md`. +When splitting large page shells, follow `.agents/skills/vue-mega-page-split/SKILL.md` +and the Frontend mega-pages table in `.agents/module-ownership.md`. - Mechanical extract only. Move or behaviour change, never both in the same change. - Prefer `internal/` or `settings/sections/` for page-private UI. Prefer colocated or `js//` for pure helpers. diff --git a/docs/agents/conventions/path-jail.md b/.agents/conventions/path-jail.md similarity index 97% rename from docs/agents/conventions/path-jail.md rename to .agents/conventions/path-jail.md index 95d09cdf..b0f89160 100644 --- a/docs/agents/conventions/path-jail.md +++ b/.agents/conventions/path-jail.md @@ -32,6 +32,6 @@ Treat MeshChatX local API access (UI session, shared host, scripted client) as a - Oracle or Hypothesis: accept only when resolved path stays under the root - Frontend mutators go through `window.api` (apiFetchGuard stays green) -Full workflow: `docs/agents/skills/path-jail-local-fs/SKILL.md`. +Full workflow: `.agents/skills/path-jail-local-fs/SKILL.md`. Reference implementation: `meshchatx/src/backend/rns_filesync_handler.py` (`_resolve_manager_path` and manager APIs). Oracle examples: `tests/backend/test_rns_filesync_security.py`, `tests/backend/test_path_jail_oracles.py`. diff --git a/docs/agents/conventions/reticulum-zen.md b/.agents/conventions/reticulum-zen.md similarity index 89% rename from docs/agents/conventions/reticulum-zen.md rename to .agents/conventions/reticulum-zen.md index 25e0c06f..fe23d551 100644 --- a/docs/agents/conventions/reticulum-zen.md +++ b/.agents/conventions/reticulum-zen.md @@ -2,9 +2,9 @@ Source philosophy: [Zen of Reticulum](https://reticulum.network/manual/zen.html). This file turns that philosophy into hard gates for MeshChatX work. -Full checklist: `docs/agents/skills/reticulum-design-gates/SKILL.md`. +Full checklist: `.agents/skills/reticulum-design-gates/SKILL.md`. -## Mental model (required) +## Mental model - There is no cloud center. Peers inhabit a fabric. Do not design features that need a privileged server, registry, or landlord API to function on the mesh. - Destination hashes are identity, not location. Do not bind mesh reachability to IP, hostname, DNS, or a fixed interface. @@ -48,4 +48,4 @@ Full checklist: `docs/agents/skills/reticulum-design-gates/SKILL.md`. ## Before you ship mesh-facing code -Run the full review checklist in `docs/agents/skills/reticulum-design-gates/SKILL.md` (clearnet-disabled operation, destination hash addressing, delay/missing-path tolerance, payload size, hostile-transport secrecy, identity/metadata redaction, no cross-identity leakage). If any gate fails, redesign. +Run the full review checklist in `.agents/skills/reticulum-design-gates/SKILL.md` (clearnet-disabled operation, destination hash addressing, delay/missing-path tolerance, payload size, hostile-transport secrecy, identity/metadata redaction, no cross-identity leakage). If any gate fails, redesign. diff --git a/docs/agents/conventions/tests.md b/.agents/conventions/tests.md similarity index 87% rename from docs/agents/conventions/tests.md rename to .agents/conventions/tests.md index 3d43895c..67c2d0cb 100644 --- a/docs/agents/conventions/tests.md +++ b/.agents/conventions/tests.md @@ -18,16 +18,16 @@ Property and fuzz tests must assert an accept or reject outcome, not only that n Refuse bare `except Exception: pass`, `never_raises`-only tests, checking a result dict has an `"ok"` key without checking its value, and mocks that always succeed under a security oracle. Prefer an independent oracle (predict accept or reject from the input, then assert the code matches), jail oracles (resolved path stays under the allowed root), closed reason sets (`ValueError` message is one of the known machine reasons), or round-trip invariants for pure parsing. -Full guidance and examples: `docs/agents/skills/test-oracles/SKILL.md`. -Path jail filesystem features: `docs/agents/skills/path-jail-local-fs/SKILL.md` and `docs/agents/conventions/path-jail.md`. -Exploratory bug hunting: `docs/agents/skills/exploratory-testing/SKILL.md`. +Full guidance and examples: `.agents/skills/test-oracles/SKILL.md`. +Path jail filesystem features: `.agents/skills/path-jail-local-fs/SKILL.md` and `.agents/conventions/path-jail.md`. +Exploratory bug hunting: `.agents/skills/exploratory-testing/SKILL.md`. ## Frontend mega-page ownership contracts - Ownership inventory: `tests/frontend/fixtures/frontend_mega_page_ownership.json` - Symbol continuity: `tests/frontend/fixtures/frontend_symbol_continuity/` - Scanner tests: `tests/frontend/frontendOwnershipContract.test.js` -- Extract workflow: `docs/agents/skills/vue-mega-page-split/SKILL.md` +- Extract workflow: `.agents/skills/vue-mega-page-split/SKILL.md` - Refresh ownership fixture only when inventory intentionally changes: `UPDATE_FRONTEND_OWNERSHIP=1 pnpm exec vitest run tests/frontend/frontendOwnershipContract.test.js -t ownership_fixture` @@ -50,7 +50,7 @@ UPDATE_HTTP_API_ROUTES=1 uv run pytest tests/backend/test_http_api_contract.py - UPDATE_WS_MESSAGE_MANIFEST=1 uv run pytest tests/backend/test_ws_json_contracts.py -k manifest_matches_meshchat ``` -JSON response schemas stay in `tests/backend/` (`api_json_contract_schemas.py`, `http_api_response_schemas.py`, registry files). Domain ownership for routes vs schemas: `docs/agents/module-ownership.md`. Extraction workflow: `docs/agents/skills/meshchat-orchestration-split/SKILL.md`. +JSON response schemas stay in `tests/backend/` (`api_json_contract_schemas.py`, `http_api_response_schemas.py`, registry files). Domain ownership for routes vs schemas: `.agents/module-ownership.md`. Extraction workflow: `.agents/skills/meshchat-orchestration-split/SKILL.md`. ## Extended Edge Case Tester (EECT) and Live Validation (LV) diff --git a/docs/agents/module-ownership.md b/.agents/module-ownership.md similarity index 99% rename from docs/agents/module-ownership.md rename to .agents/module-ownership.md index ce02fcf0..b3711cef 100644 --- a/docs/agents/module-ownership.md +++ b/.agents/module-ownership.md @@ -47,7 +47,7 @@ WS inbound handlers live in `ws/handlers_*.py` and are composed by `ws/dispatch. ## Frontend mega-pages -Placement for extracts. Follow `docs/agents/skills/vue-mega-page-split/SKILL.md`. +Placement for extracts. Follow `.agents/skills/vue-mega-page-split/SKILL.md`. Do not invent folders outside this table. | Kind | Put it here | Example | diff --git a/docs/agents/overview.md b/.agents/overview.md similarity index 88% rename from docs/agents/overview.md rename to .agents/overview.md index fc05489d..c3ac5022 100644 --- a/docs/agents/overview.md +++ b/.agents/overview.md @@ -1,7 +1,7 @@ # MeshChatX agent overview Project brief for automated agents and contributors. -Conventions and task skills live under `docs/agents/`. This file is the durable source of truth for architecture and invariants. +Conventions and task skills live under `.agents/`. This file is the durable source of truth for architecture and invariants. ## What this project is @@ -21,7 +21,7 @@ Electron and Android wrap the same backend. Website: [meshchatx.com](https://meshchatx.com) Source: [github.com/Quad4-Software/MeshChatX](https://github.com/Quad4-Software/MeshChatX) -## Design goals (do not violate casually) +## Design goals - Local-first. Works on desktop, mobile, containers, and SBCs. - Preserve Reticulum / LXMF / LXST semantics while improving UX and ops tooling. @@ -35,12 +35,10 @@ Source: [github.com/Quad4-Software/MeshChatX](https://github.com/Quad4-Software/ MeshChatX sits on Reticulum. Agents must not invent cloud-era or IP-era designs for mesh features. - Philosophy: [Zen of Reticulum](https://reticulum.network/manual/zen.html) -- Conventions: `docs/agents/conventions/reticulum-zen.md` -- Checklist skill: `docs/agents/skills/reticulum-design-gates/SKILL.md` +- Conventions: `.agents/conventions/reticulum-zen.md` +- Checklist skill: `.agents/skills/reticulum-design-gates/SKILL.md` - Always-on editor rule (when present): reticulum Zen gates under project rules -Short form: no mandatory cloud center, address destination hashes, assume hostile links, design for scarcity and delay, keep code transport-agnostic, keep identity state scoped. - ## Runtime shape ``` @@ -74,7 +72,7 @@ Critical lifecycle facts: | `meshchatx/meshchat.py` | Orchestration, CLI, lifecycle entry | | `meshchatx/src/backend/http/` | HTTP middleware, route modules, WS dispatch | | `meshchatx/src/backend/` | Managers, DB, security, Landlock, plugins | -| `docs/agents/module-ownership.md` | Domain to manager/HTTP/WS/tests map | +| `.agents/module-ownership.md` | Domain to manager/HTTP/WS/tests map | | `meshchatx/src/frontend/` | Vue 3 UI, locales, registries, helpers | | `meshchatx/public/` | Built frontend assets consumed at runtime | | `electron/` | Desktop shell around local HTTPS backend | @@ -85,8 +83,8 @@ Critical lifecycle facts: | `docs/en/` | In-app / shipped English docs | | `vendor/` | Vendored deps (LXMFy, RNS FileSync) | | `Taskfile.yml` | Preferred command entrypoints | -| `docs/agents/` | Agent guidance (this tree) | -| `AGENTS.md` | Short pointer to `docs/agents/` | +| `.agents/` | Agent guidance (this tree) | +| `AGENTS.md` | Short pointer to `.agents/` | Business rules belong in backend managers under `meshchatx/src/backend/`. Keep `meshchat.py` focused on transport and lifecycle when possible. @@ -114,7 +112,7 @@ task run task dev ``` -Optional RNS/rngit tooling (requires mesh reachability, can sometimes be significantly slower than PyPI): +Optional RNS/rngit tooling (requires mesh reachability, often slower than PyPI): ```bash task deps:backend:rns @@ -222,7 +220,7 @@ Prefer bind `127.0.0.1`, HTTPS, and auth if other local users share the host. Sensitive config changes (for example auth enable / password hash) must use CSRF-protected HTTP endpoints, not unrestricted WebSocket mutators. -Local filesystem browse/upload/download/delete APIs must path-jail to a feature or identity root. See `docs/agents/conventions/path-jail.md` and `docs/agents/skills/path-jail-local-fs/SKILL.md`. +Local filesystem browse/upload/download/delete APIs must path-jail to a feature or identity root. See `.agents/conventions/path-jail.md` and `.agents/skills/path-jail-local-fs/SKILL.md`. Password reset: `--reset-password` or `MESHCHAT_RESET_PASSWORD=true` clears the stored hash so a new password can be set in the UI. @@ -317,10 +315,6 @@ meshchatx --restore-db /path/to/backup.zip - Patch-oriented contribution flow is documented in `CONTRIBUTING.md` (LXMF patch submission is first-class for some contributors). - Generative AI policy in `CONTRIBUTING.md` requires disclosure and human review. Do not submit unreviewed bulk-generated churn. -## Agent hard rules - -Full list: `docs/agents/conventions/core.md` (mirrors the always-on editor rule). Mesh-facing designs must additionally pass the Zen / architecture gates (`reticulum-zen.md` / `reticulum-design-gates`). - ## High-risk change checklist Before finishing work in these areas, verify the matching invariants: @@ -333,21 +327,15 @@ Before finishing work in these areas, verify the matching invariants: 6. **Identity switch** - no cross-identity leakage via caches, routers, or global singletons. 7. **Migrations** - schema version bump and upgrade path tested. -## Where to read next +## Product docs -- `docs/agents/conventions/reticulum-zen.md` - Zen of Reticulum hard gates -- `docs/agents/skills/reticulum-design-gates/SKILL.md` - mesh design checklist -- `docs/en/architecture.md` - design and process overview -- `docs/en/identity-and-security.md` - identities, auth, privacy, backups -- `docs/en/getting-started.md` - UI map and first-run workflow -- `docs/en/rns-link-api.md` - generic RNS Link WebSocket API -- `docs/en/platform-guides/linux-sandbox.md` - Firejail / Bubblewrap -- `docs/en/messaging.md` - LXMF behaviour -- `CHANGELOG.md` - version-facing behaviour changes -- `CONTRIBUTING.md` - patch and AI disclosure policy +- `docs/en/architecture.md` +- `docs/en/identity-and-security.md` +- `docs/en/getting-started.md` +- `docs/en/rns-link-api.md` +- `docs/en/platform-guides/linux-sandbox.md` +- `docs/en/messaging.md` +- `CHANGELOG.md` +- `CONTRIBUTING.md` -## Agent guidance index - -- `docs/agents/README.md` - index of conventions and skills -- `docs/agents/conventions/` - surface-specific rules including Reticulum Zen and test oracles -- `docs/agents/skills/` - focused workflows including reticulum-design-gates, RRC / LXMF / LXST, pages, registries, identity restore/switch, Landlock/SQLite, migrations/backups, auth/CSRF/WS, plugins, RNS Link API, deferred startup, Electron packaging, Android bridge, test loop, test-oracles, and exploratory-testing +Conventions and skills: `.agents/README.md`. Hard rules: `.agents/conventions/core.md`. diff --git a/docs/agents/skills/android-webview-bridge/SKILL.md b/.agents/skills/android-webview-bridge/SKILL.md similarity index 91% rename from docs/agents/skills/android-webview-bridge/SKILL.md rename to .agents/skills/android-webview-bridge/SKILL.md index a9b8f8c2..aa43b31c 100644 --- a/docs/agents/skills/android-webview-bridge/SKILL.md +++ b/.agents/skills/android-webview-bridge/SKILL.md @@ -1,3 +1,8 @@ +--- +name: android-webview-bridge +description: Android WebView chooser MIME mapping, storage paths, Chaquopy boot, and external navigation. Use when changing MainActivity bridges, file pickers, or Android Python packaging. +--- + # Skill: android-webview-bridge Keep Chaquopy backend boot, WebView file choosers, storage locks, and external navigation correct on Android. @@ -51,7 +56,7 @@ Keep Chaquopy backend boot, WebView file choosers, storage locks, and external n - `meshchatx/android_codec2.py` - `meshchatx/src/backend/android_rnode/` - `meshchatx/src/frontend/js/rnode/AndroidBridge.js` -- `docs/agents/conventions/android.md` +- `.agents/conventions/android.md` ## Verification diff --git a/docs/agents/skills/auth-csrf-ws-security/SKILL.md b/.agents/skills/auth-csrf-ws-security/SKILL.md similarity index 89% rename from docs/agents/skills/auth-csrf-ws-security/SKILL.md rename to .agents/skills/auth-csrf-ws-security/SKILL.md index cfa65621..86b01bf2 100644 --- a/docs/agents/skills/auth-csrf-ws-security/SKILL.md +++ b/.agents/skills/auth-csrf-ws-security/SKILL.md @@ -1,3 +1,8 @@ +--- +name: auth-csrf-ws-security +description: CSRF on mutating HTTP, window.api callers, and WebSocket mutator denylist. Use when adding POST routes, auth/password changes, or WS types that mutate state. +--- + # Skill: auth-csrf-ws-security Keep mutating HTTP behind CSRF and `window.api`. Never move security-boundary settings onto open WebSocket mutators. diff --git a/docs/agents/skills/contribution-registries/SKILL.md b/.agents/skills/contribution-registries/SKILL.md similarity index 95% rename from docs/agents/skills/contribution-registries/SKILL.md rename to .agents/skills/contribution-registries/SKILL.md index a94c5519..ab70b0d2 100644 --- a/docs/agents/skills/contribution-registries/SKILL.md +++ b/.agents/skills/contribution-registries/SKILL.md @@ -1,3 +1,8 @@ +--- +name: contribution-registries +description: Nav, tools, commands, settings search, and WS events through registries. Use when adding a discoverable page, command, settings section, or WS handler. +--- + # Skill: contribution-registries Wire nav, tools, commands, settings search, and WebSocket events through registries instead of hardcoding shell or App.vue dispatch. diff --git a/docs/agents/skills/database-migrations-backups/SKILL.md b/.agents/skills/database-migrations-backups/SKILL.md similarity index 90% rename from docs/agents/skills/database-migrations-backups/SKILL.md rename to .agents/skills/database-migrations-backups/SKILL.md index 06cb3401..f1687ad9 100644 --- a/docs/agents/skills/database-migrations-backups/SKILL.md +++ b/.agents/skills/database-migrations-backups/SKILL.md @@ -1,3 +1,8 @@ +--- +name: database-migrations-backups +description: SQLite schema bumps, backups, snapshots, and restore safety. Use when changing migrations or backup/restore paths. Do not conflate identity-key restore with zip restore. +--- + # Skill: database-migrations-backups Bump schema versions correctly, keep backups and snapshots safe, and never conflate identity-key restore with full database zip restore. @@ -47,7 +52,7 @@ This writes `tests/backend/fixtures/schema_versions/schema_v{N}.db` for latest, ## Two restore operations -Private key only vs full history/settings/identity tree restore are different operations with different APIs. Full table: `docs/agents/overview.md` (Identity key restore vs database restore section). +Private key only vs full history/settings/identity tree restore are different operations with different APIs. Full table: `.agents/overview.md` (Identity key restore vs database restore section). Details for pickers and tutorial copy: `identity-restore`. ## Key files diff --git a/docs/agents/skills/deferred-network-startup/SKILL.md b/.agents/skills/deferred-network-startup/SKILL.md similarity index 90% rename from docs/agents/skills/deferred-network-startup/SKILL.md rename to .agents/skills/deferred-network-startup/SKILL.md index 8fbd382f..ed3fd430 100644 --- a/docs/agents/skills/deferred-network-startup/SKILL.md +++ b/.agents/skills/deferred-network-startup/SKILL.md @@ -1,3 +1,8 @@ +--- +name: deferred-network-startup +description: HTTP-up vs RNS-ready status, 503s for retryable init, Electron loading probes, Android RNS panic containment. Use when changing boot order or early API behaviour. +--- + # Skill: deferred-network-startup Treat HTTP-up as distinct from RNS-ready. Gate UI on `/api/v1/status`, return 503 for retryable init failures, and contain RNS panic on Android. diff --git a/docs/agents/skills/electron-frozen-packaging/SKILL.md b/.agents/skills/electron-frozen-packaging/SKILL.md similarity index 90% rename from docs/agents/skills/electron-frozen-packaging/SKILL.md rename to .agents/skills/electron-frozen-packaging/SKILL.md index 0b35b31b..e71fba4f 100644 --- a/docs/agents/skills/electron-frozen-packaging/SKILL.md +++ b/.agents/skills/electron-frozen-packaging/SKILL.md @@ -1,3 +1,8 @@ +--- +name: electron-frozen-packaging +description: Frozen desktop spawn, --meshchatx-run-module re-entry, loading probes, crash recovery, external URL guards. Use when changing Electron main process or packaged helper spawn. +--- + # Skill: electron-frozen-packaging Package and recover the desktop shell correctly: frozen subprocess re-entry, loading probes, crash/offline DB restore, and external URL guards. diff --git a/docs/agents/skills/exploratory-testing/SKILL.md b/.agents/skills/exploratory-testing/SKILL.md similarity index 82% rename from docs/agents/skills/exploratory-testing/SKILL.md rename to .agents/skills/exploratory-testing/SKILL.md index 060c122d..37c50f18 100644 --- a/docs/agents/skills/exploratory-testing/SKILL.md +++ b/.agents/skills/exploratory-testing/SKILL.md @@ -1,3 +1,8 @@ +--- +name: exploratory-testing +description: Adversarial bug hunting with explicit hypotheses and oracle-backed confirmation. Use when the user asks to find bugs, fuzz a subsystem, or audit edge cases. +--- + # Skill: exploratory-testing Hunt bugs with explicit hypotheses and oracle-backed confirmation. Use when the user asks to find bugs, fuzz a subsystem, or audit edge cases beyond happy-path unit tests. @@ -49,7 +54,7 @@ When reporting to the user: ## Related -- `docs/agents/skills/test-oracles/SKILL.md` -- `docs/agents/skills/rrc-relay-chat/SKILL.md` -- `docs/agents/skills/reticulum-design-gates/SKILL.md` -- `docs/agents/conventions/tests.md` +- `.agents/skills/test-oracles/SKILL.md` +- `.agents/skills/rrc-relay-chat/SKILL.md` +- `.agents/skills/reticulum-design-gates/SKILL.md` +- `.agents/conventions/tests.md` diff --git a/docs/agents/skills/identity-restore/SKILL.md b/.agents/skills/identity-restore/SKILL.md similarity index 82% rename from docs/agents/skills/identity-restore/SKILL.md rename to .agents/skills/identity-restore/SKILL.md index 8e8ce3ae..d600453f 100644 --- a/docs/agents/skills/identity-restore/SKILL.md +++ b/.agents/skills/identity-restore/SKILL.md @@ -1,3 +1,8 @@ +--- +name: identity-restore +description: Identity key import vs database zip restore, tutorial and Android pickers. Use when changing identity restore UI, APIs, or file accept lists. +--- + # Skill: identity-restore Identity key import vs database zip restore, tutorial and Android pickers. @@ -6,7 +11,7 @@ Identity key import vs database zip restore, tutorial and Android pickers. ## Two different restores -Full table of goal / UI / API for both restore paths: `docs/agents/overview.md` (Identity key restore vs database restore section). +Full table of goal / UI / API for both restore paths: `.agents/overview.md` (Identity key restore vs database restore section). Never imply identity-key import restores message history. ## Guards checklist diff --git a/docs/agents/skills/identity-switch-teardown/SKILL.md b/.agents/skills/identity-switch-teardown/SKILL.md similarity index 90% rename from docs/agents/skills/identity-switch-teardown/SKILL.md rename to .agents/skills/identity-switch-teardown/SKILL.md index ad7d5896..3b17c781 100644 --- a/docs/agents/skills/identity-switch-teardown/SKILL.md +++ b/.agents/skills/identity-switch-teardown/SKILL.md @@ -1,3 +1,8 @@ +--- +name: identity-switch-teardown +description: Live identity switch by tearing down IdentityContext and clearing caches. Use when adding managers that hold destinations, timers, or DB handles. +--- + # Skill: identity-switch-teardown Switch identities by tearing down the full `IdentityContext` and clearing frontend caches so routers and managers never leak cross-identity state. diff --git a/docs/agents/skills/landlock-sqlite/SKILL.md b/.agents/skills/landlock-sqlite/SKILL.md similarity index 94% rename from docs/agents/skills/landlock-sqlite/SKILL.md rename to .agents/skills/landlock-sqlite/SKILL.md index a45ddbe6..0a16c354 100644 --- a/docs/agents/skills/landlock-sqlite/SKILL.md +++ b/.agents/skills/landlock-sqlite/SKILL.md @@ -1,3 +1,8 @@ +--- +name: landlock-sqlite +description: Linux Landlock and Windows AppContainer with SQLite temp_store, plus subprocess and user-local CLI probes. Use when changing sandbox rules, conversation queries, or Popen of external binaries. +--- + # Skill: landlock-sqlite Landlock / Windows AppContainer + SQLite conversation-load failures (temp_store, slim queries, memory pressure). Also covers subprocess and user-local CLI breakage under Linux Landlock. diff --git a/docs/agents/skills/lxmf-messaging/SKILL.md b/.agents/skills/lxmf-messaging/SKILL.md similarity index 94% rename from docs/agents/skills/lxmf-messaging/SKILL.md rename to .agents/skills/lxmf-messaging/SKILL.md index 3939d1d5..9c85c5f9 100644 --- a/docs/agents/skills/lxmf-messaging/SKILL.md +++ b/.agents/skills/lxmf-messaging/SKILL.md @@ -1,3 +1,8 @@ +--- +name: lxmf-messaging +description: LXMF send/receive, stamps, propagation nodes, attachments, inbound cancel. Use when changing messaging, LXMRouter wiring, or conversation UI. +--- + # Skill: lxmf-messaging Change LXMF messaging, stamps, propagation, or attachments without breaking local-first mesh delivery or identity scoping. diff --git a/docs/agents/skills/lxst-telephony/SKILL.md b/.agents/skills/lxst-telephony/SKILL.md similarity index 93% rename from docs/agents/skills/lxst-telephony/SKILL.md rename to .agents/skills/lxst-telephony/SKILL.md index 3d49fa0f..701a41bc 100644 --- a/docs/agents/skills/lxst-telephony/SKILL.md +++ b/.agents/skills/lxst-telephony/SKILL.md @@ -1,3 +1,8 @@ +--- +name: lxst-telephony +description: LXST calls, audio WebSocket, duplex/PTT, voicemail. Use when changing TelephoneManager, call UI, or /ws/telephone/audio. +--- + # Skill: lxst-telephony Change LXST telephony or call audio without treating MeshChatX as a cloud PBX or leaking identity-scoped call state. diff --git a/docs/agents/skills/meshchat-orchestration-split/SKILL.md b/.agents/skills/meshchat-orchestration-split/SKILL.md similarity index 89% rename from docs/agents/skills/meshchat-orchestration-split/SKILL.md rename to .agents/skills/meshchat-orchestration-split/SKILL.md index 79a897b9..92330224 100644 --- a/docs/agents/skills/meshchat-orchestration-split/SKILL.md +++ b/.agents/skills/meshchat-orchestration-split/SKILL.md @@ -1,3 +1,8 @@ +--- +name: meshchat-orchestration-split +description: Extract HTTP routes and WS handlers under backend/http without behaviour change. Use when moving handlers among routes/.py or ws/handlers_*.py. +--- + # Skill: meshchat-orchestration-split Extract or split HTTP routes and WebSocket handlers under `meshchatx/src/backend/http/` @@ -11,9 +16,9 @@ without changing behaviour. Also read: -- `docs/agents/module-ownership.md` -- `docs/agents/conventions/backend.md` -- `docs/agents/conventions/tests.md` +- `.agents/module-ownership.md` +- `.agents/conventions/backend.md` +- `.agents/conventions/tests.md` ## Hard rules @@ -26,7 +31,7 @@ Also read: 4. Handlers use `app` where the original used `self`. 5. No new business logic in route modules. Parse, call manager or app method, return response. 6. Identity lifecycle and LXMF callbacks stay on `ReticulumMeshChat` until lifecycle packaging. -7. Follow inventory names in `docs/agents/module-ownership.md`. Do not invent alternate folders. +7. Follow inventory names in `.agents/module-ownership.md`. Do not invent alternate folders. 8. Domain splits start from existing `routes/.py` modules or residual shared helpers. Do not re-extract routes from `meshchat.py`. 9. One-shot extract scripts that rewrote `meshchat.py` were removed. Do not revive them. diff --git a/.agents/skills/no-ai-slop/SKILL.md b/.agents/skills/no-ai-slop/SKILL.md new file mode 100644 index 00000000..1ba99f20 --- /dev/null +++ b/.agents/skills/no-ai-slop/SKILL.md @@ -0,0 +1,105 @@ +--- +name: no-ai-slop +description: "Rules and worked examples for writing prose that does not read like AI-generated slop. Consult before writing or editing any prose." +--- + +# No AI Slop + +The full rule list lives in `references/rules.md` (rules 1 through 24). This skill turns the rules that have worked examples into actionable guidance: each shows a WRONG version (the slop) and a RIGHT version (the fix). The pattern behind every fix is the same: replace the vague claim with a specific, checkable fact. + +## Rule 1: No emdashes + +The character is banned. Use a semicolon, a period, a comma, or restructure. + +- WRONG: "The policy -- which affected millions -- was later reversed." +- RIGHT: "The policy affected millions of devices. The company reversed it in December 2017." + +## Rule 4: No intensifiers + +"Significantly", "dramatically", "extremely" and their kin are placeholders for evidence. Replace the word with the number it was standing in for. + +- WRONG: "The pricing was significantly higher than the cost of the part." +- RIGHT: "They charged $1,200 for a repair that needed a $5 chip." + +## Rule 5: No hollow statements + +A sentence that asserts importance without a detail says nothing. End every claim on a concrete fact. + +- WRONG: "This practice has had a significant impact on people." +- RIGHT: "The company replaced 11 million batteries in 2018, against the 1 to 2 million it had expected." + +## Rule 7: No structural slop (repetitive layouts) + +Three sections built from the same template read as machine output, even when each fact is true. Vary paragraph count, sentence rhythm, and how each section opens. + +- WRONG (three sections, identical shape): + ``` + In [year], [party] did [thing]. This affected [number] people. [Party] responded by [action]. + In [year], [party] did [thing]. This affected [number] people. [Party] responded by [action]. + In [year], [party] did [thing]. This affected [number] people. [Party] responded by [action]. + ``` +- RIGHT (vary the shape): + ``` + Section one: a detailed narrative with timeline and context across two paragraphs. + Section two: a two-sentence summary, because the event is thinly documented. + Section three: opens with the party's stated justification, then the contradicting evidence. + ``` + +## Rule 11: No filler phrases + +"In today's world", "It's important to note", "When it comes to" add length, not meaning. Open on the fact. + +- WRONG: "In today's world, planned obsolescence affects many devices." +- RIGHT: "Apple, Samsung, and Google have each faced lawsuits alleging planned obsolescence." + +## Rule 13: Write like a researcher, not a copywriter + +If a sentence could sit on any advocacy or marketing site without changing a word, it is generic. Anchor it to something checkable. + +- WRONG: "People deserve the right to repair their own devices." +- RIGHT: "The FTC voted 5-0 in July 2021 to step up enforcement against illegal repair restrictions." + +## Rule 15: No weasel words + +"May potentially", "can help to", "might be able to" hedge a claim into meaninglessness. Either the thing happens or it does not. Say which. + +- WRONG: "Serialization may potentially prevent independent repair." +- RIGHT: "Replacing an iPhone 15 camera module without the manufacturer's calibration software disables optical image stabilization." + +## Rule 16: No dramatic headings + +A heading names what the section holds. It does not tease, dramatize, or abstract. + +- WRONG: "The Hidden Cost of Planned Obsolescence" +- RIGHT: "Economic impact of shortened product lifespans" + +## Rule 19: No fabricated attributions + +Never put a position in a named person's mouth from inference. State only what they actually did or said, with the real source. + +- WRONG: "Senator Smith has argued that the right to repair is essential." +- RIGHT: "Senator Smith co-sponsored the Fair Repair Act in January 2024." + +## Root-cause differentiation + +When you contrast two things, name the concrete difference that separates them. Do not assert that one is exempt, newer, better, or unaffected without saying what specifically makes it so. + +- WRONG: "2020+ Leaf models are unaffected and use the MyNISSAN app instead." +- RIGHT: "2020+ Leaf models shipped with 4G/LTE telematics units connected to a newer cloud platform, replacing the 2G/3G units in earlier models. Those vehicles use the MyNISSAN app, which talks to a different backend." + +Whenever you say A differs from B, name the part, the version, the date, the mechanism, or the supply-chain change that makes the difference real. If you do not have that detail, do not imply the difference exists. + +## Self-check before returning text + +Run this pass on every piece of prose before you hand it back. The full banned lists are in `references/ai-writing-detection.md`; check against them directly. + +1. Search for the emdash character. Remove every one (Rule 1). +2. Scan for banned verbs (delve, leverage, utilize, foster, bolster, underscore, unveil, streamline) and replace with plain equivalents. +3. Scan for banned adjectives and intensifiers (robust, comprehensive, pivotal, seamless, significantly, extremely, truly) and cut or replace. +4. Scan for banned transitions and openers (Furthermore, Moreover, That being said, In today's world, It's worth noting that). +5. Check every number: is it real and attributable? If not, cut it (Rule 2). +6. Check every sentence ends on a concrete detail, not an assertion of importance (Rule 5). +7. Check headings: does each name the content rather than tease it (Rule 16)? +8. Check for repeated points and repeated section shapes (Rules 6, 7). +9. Count hedging markers per paragraph. More than three is a red flag. +10. Read it aloud. If a phrase would sound unnatural to a colleague, rewrite it. diff --git a/.agents/skills/no-ai-slop/references/ai-writing-detection.md b/.agents/skills/no-ai-slop/references/ai-writing-detection.md new file mode 100644 index 00000000..29fb6d91 --- /dev/null +++ b/.agents/skills/no-ai-slop/references/ai-writing-detection.md @@ -0,0 +1,388 @@ +# AI Writing Detection + +Words, phrases, punctuation patterns, structural signals, and statistical measures commonly associated with AI-generated text. Avoid these to ensure writing sounds natural and human. + +Sources: Grammarly (2025), Microsoft 365 Life Hacks (2025), GPTHuman (2025), Walter Writes (2025), Textero (2025), Plagiarism Today (2025), Rolling Stone (2025), MDPI Blog (2025), isgpt.org corpus analysis (2025), ACL hedging study (2024), Wikipedia AI content detection project (2025), Segmental entropy research (arxiv, 2025) + +--- + +## Contents +- Em Dashes: The Primary AI Tell +- Overused Verbs +- Overused Adjectives +- Overused Transitions and Connectors +- Phrases That Signal AI Writing (Opening, Transitional, Concluding, Structural, Inflated Symbolism) +- Filler Words and Empty Intensifiers +- Heading Anti-Patterns +- Academic-Specific AI Tells +- Hallucinated Markup Artifacts +- Hedging and Epistemic Modality Overload +- Structural and Statistical Patterns +- Model-Family-Specific Tells +- False Positive Prevention +- How to Self-Check + +## Em Dashes: The Primary AI Tell + +**The em dash (—) has become one of the most reliable markers of AI-generated content.** + +Em dashes are longer than hyphens (-) and are used for emphasis, interruptions, or parenthetical information. While they have legitimate uses in writing, AI models drastically overuse them. + +### Why Em Dashes Signal AI Writing +- AI models were trained on edited books, academic papers, and style guides where em dashes appear frequently +- AI uses em dashes as a shortcut for sentence variety instead of commas, colons, or parentheses +- Most human writers rarely use em dashes because they don't exist as a standard keyboard key +- The overuse is so consistent that it has become the unofficial signature of ChatGPT writing + +### What To Do Instead +| Instead of | Use | +|------------|-----| +| The results—which were surprising—showed... | The results, which were surprising, showed... | +| This approach—unlike traditional methods—allows... | This approach, unlike traditional methods, allows... | +| The study found—as expected—that... | The study found, as expected, that... | +| Communication skills—both written and verbal—are essential | Communication skills (both written and verbal) are essential | + +### Guidelines +- Use commas for most parenthetical information +- Use colons to introduce explanations or lists +- Use parentheses for supplementary information +- Reserve em dashes for rare, deliberate emphasis only +- If you find yourself using more than one em dash per page, revise + +--- + +## Overused Verbs + +| Avoid | Use Instead | +|-------|-------------| +| delve (into) | explore, examine, investigate, look at | +| leverage | use, apply, draw on | +| optimise | improve, refine, enhance | +| utilise | use | +| facilitate | help, enable, support | +| foster | encourage, support, develop, nurture | +| bolster | strengthen, support, reinforce | +| underscore | emphasise, highlight, stress | +| unveil | reveal, show, introduce, present | +| navigate | manage, handle, work through | +| streamline | simplify, make more efficient | +| enhance | improve, strengthen | +| endeavour | try, attempt, effort | +| ascertain | find out, determine, establish | +| elucidate | explain, clarify, make clear | + +--- + +## Overused Adjectives + +| Avoid | Use Instead | +|-------|-------------| +| robust | strong, reliable, thorough, solid | +| comprehensive | complete, thorough, full, detailed | +| pivotal | key, critical, central, important | +| crucial | important, key, essential, critical | +| vital | important, essential, necessary | +| transformative | significant, important, major | +| cutting-edge | new, advanced, recent, modern | +| groundbreaking | new, original, significant | +| innovative | new, original, creative | +| seamless | smooth, easy, effortless | +| intricate | complex, detailed, complicated | +| nuanced | subtle, complex, detailed | +| multifaceted | complex, varied, diverse | +| holistic | complete, whole, comprehensive | + +### Overused Metaphorical Nouns (2025-2026) +AI models use these nouns metaphorically to inject false gravitas. Literal uses are fine. + +| Avoid (metaphorical) | Acceptable (literal) | +|-------|-------------| +| tapestry ("a tapestry of regulations") | tapestry (actual woven fabric) | +| symphony ("a symphony of features") | symphony (actual musical composition) | +| beacon ("a beacon of hope") | beacon (actual light or signal device) | +| realm ("in the realm of cybersecurity") | realm (actual kingdom or territory) | +| testament ("a testament to innovation") | testament (actual legal document, e.g., last will and testament) | + +--- + +## Overused Transitions and Connectors + +| Avoid | Use Instead | +|-------|-------------| +| furthermore | also, in addition, and | +| moreover | also, and, besides | +| notwithstanding | despite, even so, still | +| that being said | however, but, still | +| at its core | essentially, fundamentally, basically | +| to put it simply | in short, simply put | +| it is worth noting that | note that, importantly | +| in the realm of | in, within, regarding | +| in the landscape of | in, within | +| in today's [anything] | currently, now, today | + +--- + +## Phrases That Signal AI Writing + +### Opening Phrases to Avoid +- "In today's fast-paced world..." +- "In today's digital age..." +- "In an era of..." +- "In the ever-evolving landscape of..." +- "In the realm of..." +- "It's important to note that..." +- "Let's delve into..." +- "Imagine a world where..." + +### Transitional Phrases to Avoid +- "That being said..." +- "With that in mind..." +- "It's worth mentioning that..." +- "At its core..." +- "To put it simply..." +- "In essence..." +- "This begs the question..." + +### Concluding Phrases to Avoid +- "In conclusion..." +- "To sum up..." +- "By [doing X], you can [achieve Y]..." +- "In the final analysis..." +- "All things considered..." +- "At the end of the day..." + +### Structural Patterns to Avoid +- "Whether you're a [X], [Y], or [Z]..." (listing three examples after "whether") +- "It's not just [X], it's also [Y]..." +- "Think of [X] as [elaborate metaphor]..." +- Starting sentences with "By" followed by a gerund: "By understanding X, you can Y..." +- Contrasting parallelisms: "It's not X. It's Y." or "It's not about X, it's about Y." More than two of these in a 500-word block is a high-confidence AI indicator. + +### Inflated Symbolism Phrases (2025-2026 AI Tells) +These multi-word phrases appear hundreds of times more frequently in AI-generated text than in human baselines (corpus analysis, isgpt.org 2025): +- "provide a valuable insight" (468x more frequent in AI text) +- "left an indelible mark" (317x) +- "play a significant role in shaping" (207x) +- "an unwavering commitment" (202x) +- "open a new avenue" (174x) +- "a stark reminder" (166x) +- "gain a comprehensive understanding" (120x) +- "serves as a testament" +- "watershed moment" +- "deeply rooted" + +--- + +## Heading Anti-Patterns + +AI-generated content frequently uses narrative, dramatic, or clickbait heading structures that read like thriller chapter titles. These patterns signal low-effort AI writing even when the body text is clean. All headings must describe the section content directly and technically. + +### Banned Heading Structures + +| Pattern | Bad Example | Good Replacement | +|---------|-------------|------------------| +| "The [Concept] Trap" | "The Initialization Trap" | "Import vs. Initialize: DDF Metadata Destruction Risk" | +| "The [Adjective] [Noun]" drama | "The Hidden Danger" | "Firmware Corruption After Sudden Power Loss" | +| "The [Noun] [Dramatic Noun]" | "The Silent Killer" | "Gradual Bad Sector Growth on Aging Platters" | +| "Why [Action] [Dramatic Verb] [Object]" | "Why Rebuilding Destroys Everything" | "How Forced Rebuilds Overwrite Parity on Degraded Arrays" | +| "[Noun]: The [Adjective] [Noun]" | "Encryption: The Hidden Trap" | "Hardware AES-256 Encryption on WD Passport Bridge Boards" | +| "The [Noun] You [Emotion Verb]" | "The Risk You Overlook" | "Unmonitored SMART Threshold Warnings" | + +### How to Self-Check Headings + +1. Could this heading serve as a thriller chapter title or YouTube clickbait thumbnail? If yes, rewrite it. +2. Does the heading describe what the section contains, or does it tease it? Headings describe; they do not tease. +3. Remove "The" from the beginning of any heading and check if it still uses a dramatic noun pairing. If so, rewrite. +4. A good heading reads like an entry in a technical manual index: specific, descriptive, and boring to non-specialists. + +--- + +## Filler Words and Empty Intensifiers + +These words often add nothing to meaning. Remove them or find specific alternatives: + +- absolutely +- actually +- basically +- certainly +- clearly +- definitely +- essentially +- extremely +- fundamentally +- incredibly +- interestingly +- naturally +- obviously +- quite +- really +- significantly +- simply +- surely +- truly +- ultimately +- undoubtedly +- very + +--- + +## Academic-Specific AI Tells + +| Avoid | Use Instead | +|-------|-------------| +| shed light on | clarify, explain, reveal | +| pave the way for | enable, allow, make possible | +| a myriad of | many, numerous, various | +| a plethora of | many, numerous, several | +| paramount | very important, essential, critical | +| pertaining to | about, regarding, concerning | +| prior to | before | +| subsequent to | after | +| in light of | because of, given, considering | +| with respect to | about, regarding, for | +| in terms of | regarding, for, about | +| the fact that | that (or rewrite sentence) | + +--- + +## Hallucinated Markup Artifacts + +When AI generates wikitext, it sometimes hallucinates citation markup from its training data. These are 100% confidence indicators of unedited AI output: + +| Artifact | Origin | +|----------|--------| +| `oaicite` | OpenAI ChatGPT citation placeholder | +| `contentReference` | OpenAI internal reference tag | +| `grok_card` | xAI Grok citation tag | +| `attributableIndex` | AI attribution tracking artifact | +| `turn0search0` | ChatGPT search result placeholder | + +Any occurrence of these strings in wikitext means the text was pasted from an AI tool without editing. Zero tolerance. + +--- + +## Hedging and Epistemic Modality Overload + +AI models hedge 4-7x more than human writers (ACL 2024 study, 12,000 technical documents). Because models are trained to avoid stating hallucinations as facts, they default to blanket hedging even for established facts. + +### Hedging Markers +**Epistemic modals** (45% of AI hedges): may, might, could, potentially +**Cognitive verbs** (25%): I think, I believe, it seems, it appears +**Adverbs of limitation** (20%): probably, generally, usually, arguably, likely +**Explicit uncertainty markers**: unclear, remains to be seen, further research is needed + +### Thresholds +- **Per-paragraph:** More than 3 hedging instances in a single paragraph warrants scrutiny +- **Per-1000-words:** More than 8 hedging markers per 1,000 words in declarative sections (Background, History, Timeline) indicates AI generation. These sections state established facts. +- **Appropriate hedging:** Sections discussing pending legislation, ongoing litigation, or genuinely disputed facts should hedge. Do not flag hedging in those contexts. + +### AI Hedging Phrases to Flag +- "It is worth noting that..." +- "It should be noted that..." +- "One could argue that..." +- "While X, Y remains..." +- "Though precise thresholds can vary depending on..." +- "It is widely acknowledged that..." + +### Human vs. AI Hedging +Humans hedge contextually, grounding uncertainty in specific evidence: "The FTC's 2024 enforcement data suggests a 12% increase." AI hedges with blanket qualifiers on established facts: "It is widely acknowledged that repair restrictions may potentially impact consumers." + +--- + +## Structural and Statistical Patterns + +Beyond lexical tells, AI text exhibits measurable structural uniformity that human writing does not. + +### Paragraph Length Uniformity +AI aims for visual symmetry. Paragraphs tend toward identical sentence counts (typically 3-4 sentences each). Human writing varies paragraph length based on sub-topic complexity. +- **Threshold:** If all paragraphs in a section are within 15% of each other in word count, the section is likely AI-generated. +- **Exception:** Bulleted lists, tables, and template fields are structurally uniform by design. + +### Sentence Length Uniformity (Burstiness) +Human writing alternates between short, punchy sentences and long, clause-heavy ones. AI sentences cluster uniformly around 15-20 words. +- **Threshold:** If a 500-word block contains no sentences under 8 words or over 30 words, it lacks human burstiness. +- **Human baseline:** Human text exhibits 3+ distinct syntactic patterns per 100 words. AI text shows 1.5 or fewer. + +### Transition Density +AI over-relies on transition words and adverbial clauses to maintain flow between paragraphs. +- **Threshold:** If more than 30% of paragraphs in an article begin with a transition word or adverbial clause, the text is structurally artificial. + +### Opening-Word Repetition +Three or more consecutive paragraphs starting with the same word or phrase pattern indicates mechanical generation. Vary opening words. + +### Segmental Entropy +AI maintains flat stylistic consistency from introduction through conclusion. Human writers naturally vary pacing, complexity, and sentence structure between sections. +- **Threshold:** Calculate sentence length variance separately for the introduction, body, and conclusion. If variance differs by less than 10% across all three segments, the text was likely generated as a single pass by AI. +- **Why this matters:** Human introductions tend to be tighter and more declarative. Human body sections are denser with longer sentences. Human conclusions shift register. AI maintains a monotone throughout. + +### Contrasting Parallelism Overuse +2025-era models overuse sequential contrasting structures to simulate punchy emphasis: +- "It's not X, it's Y." +- "It's not about X, it's about Y." +- "The issue isn't X. The issue is Y." +- **Threshold:** More than two contrasting parallelisms in a 500-word block. + +--- + +## Model-Family-Specific Tells + +Different AI model families produce distinct stylistic fingerprints based on their training and RLHF tuning. + +### GPT-4o / GPT-4.5 (OpenAI) +- Heavy use of bullet-point formatting and structured lists +- Staccato short-sentence contrasting: "It's not X. It's Y." used to simulate punchy copy +- Rhetorical colon abuse: "Here's the thing:", "Think about it:", "The bottom line:", "The reality:" +- Over-structures arguments into numbered steps + +### Claude 3.5 / Claude 4 (Anthropic) +- Better sentence length variation than GPT, but still exhibits flat segmental entropy +- Overly polite and conciliatory transitions: "It's worth considering that", "To be fair", "That said" +- Leans toward poetic and metaphorical prose with words like "nuanced," "complexities" +- Loses thread in long documents and resorts to increasingly generic transitions +- Tends toward diplomatic hedging even when stating documented facts + +### Common Across All Models +- Uniform paragraph lengths +- Predictable section ordering (Background > Details > Impact > Response) +- Citation clustering at paragraph ends rather than distributed throughout sentences +- Excessive boldface on concepts, product names, and inline headers + +--- + +## False Positive Prevention + +### Exclusion Zones +Lexical scans must NOT flag text inside: +- Direct quotes (`"..."`) from cited sources +- Titles, names, and other verbatim values taken from a source +- Code, configuration, or markup that is being shown as an example + +### Context-Aware Severity +If a banned word appears immediately adjacent to specific named entities (proper nouns, statute numbers, dates, dollar amounts), it is more likely being used with technical meaning than as AI filler. Reduce flag severity. +- **Higher severity:** "a comprehensive examination of the issues" (abstract nouns, no specifics) +- **Lower severity:** "comprehensive audit by the FTC in 2024" (specific entity, specific date) + +### Metaphorical vs. Literal Distinction +These words require bigram context checking. Only flag metaphorical uses: +- ecosystem: "Apple's software ecosystem" (OK) vs. "the repair ecosystem" (flag) +- landscape: "Arizona landscape" (OK) vs. "the regulatory landscape" (flag) +- navigate: "navigate the website" (OK) vs. "navigate the regulatory process" (flag) +- tapestry: "medieval tapestry" (OK) vs. "a tapestry of regulations" (flag) +- symphony: "Beethoven's symphony" (OK) vs. "a symphony of features" (flag) +- beacon: "lighthouse beacon" (OK) vs. "a beacon of hope" (flag) +- testament: "last will and testament" (OK) vs. "a testament to innovation" (flag) + +--- + +## How to Self-Check + +1. Read your text aloud. If phrases sound unnatural in speech, revise them +2. Ask: "Would I say this in a conversation with a colleague?" +3. Check for repetitive sentence structures +4. Look for clusters of the words listed above +5. Ensure varied sentence lengths (not all similar length) +6. Verify each intensifier adds genuine meaning +7. Count hedging markers per paragraph. More than 3 in a single paragraph is a red flag. +8. Check paragraph word counts within each section. If they are all similar, vary them. +9. Search for hallucinated markup: `oaicite`, `contentReference`, `turn0search0`, `grok_card` +10. Check if your introduction, body, and conclusion have different pacing and sentence complexity diff --git a/.agents/skills/no-ai-slop/references/rules.md b/.agents/skills/no-ai-slop/references/rules.md new file mode 100644 index 00000000..673a09e8 --- /dev/null +++ b/.agents/skills/no-ai-slop/references/rules.md @@ -0,0 +1,56 @@ +# No AI slop rules (1 through 24) + +Upstream source: [realrossmanngroup/no_ai_slop_writing_rules](https://github.com/realrossmanngroup/no_ai_slop_writing_rules) `CLAUDE.md`. +In this repo there is no project `CLAUDE.md` for these rules. Use this file. + +These are non-negotiable. Violating any of them makes the output unusable. + +1. **No emdashes.** The character is banned. Use a period, a comma, parentheses, or restructure the sentence. MeshChatX docs also ban semicolons in comments and docs you write, so prefer a period or a comma here. + +2. **No unsourced statistics.** Every number must be real and attributable. If you cannot point to where it comes from, do not write it. A made-up figure is worse than no figure. + +3. **No parenthetical clarifications in headings.** Trust the reader. + +4. **No intensifiers.** "Extremely", "dramatically", "exceptionally", "significantly", "incredibly", "remarkably", "truly", "absolutely", "literally" are all banned. Prove it with a fact or cut the word. + +5. **No hollow statements.** Every claim must end with a concrete, verifiable detail. If it cannot, delete the sentence. + +6. **No repeated talking points.** Say it once. Duplicates are padding. + +7. **Vary structure.** Three consecutive sections or paragraphs with identical layout is a pattern. Break it. + +8. **Reference without narrating the reference.** Do not write "as discussed above" or "as we will see." Make the connection and move on. + +9. **No performative urgency without a reason.** "Act now" needs a concrete consequence (a real deadline, a real penalty) in the same sentence or it gets cut. + +10. **No scare quotes on normal words.** Use quotation marks only for actual quotations from a named source. + +11. **No filler phrases.** Banned: "In today's world", "It's important to note", "When it comes to", "At the end of the day", "In the realm of", "It goes without saying", "This is where X comes in", "Look no further", "Our team of experts." + +12. **Never start a sentence with "Whether you're."** + +13. **Write like a researcher, not a copywriter.** Direct, specific, well-grounded. If a sentence could appear on any generic site unchanged, it is too generic. Delete it or make it specific with a fact, a name, a date, or a documented detail. + +14. **No synthetic enthusiasm.** Do not add exclamation marks or cheerleading. State the facts. The evidence carries the weight. + +15. **No weasel words.** "Helps ensure", "may be able to", "can potentially": either it does or it does not. Commit or cut. + +16. **No narrative, dramatic, or AI-generic headings.** Headings must be concrete and descriptive. Do not use narrative framing ("The Right to Repair Trap"), thriller-style mystery ("The Hidden Cost of Serialization"), clickbait structure ("Why Apple Destroys Your Right to Repair"), or vague analytical headings ("Broader pattern", "Broader implications", "Wider context", "Larger trend", "Industry-wide impact"). A heading describes what the section contains, not what it means. Name the subject, not the abstraction. + +17. **No fabricated case studies or scenarios.** Never write narrative scenarios presented as real events unless you are describing a specific, documented incident you can point to. Do not invent outcomes, actions, or stories. + +18. **No fabricated history or milestones.** Do not invent dates for events, launches, founding, or milestones. Every date and event must be real. + +19. **No fabricated attributions.** Never claim a person, organization, or company said something unless it is real and verifiable. Writing "Senator X stated..." or "the company argued..." without a real source is a fabrication and a defamation risk. Every attributed quote or position must trace to a real document, transcript, public statement, or report. Do not assume what someone's position is based on their party, role, or reputation. + +20. **No AI transition phrases.** Banned: "Furthermore", "Moreover", "Notwithstanding", "That being said", "At its core", "In essence", "It is worth noting that", "In the landscape of", "To put it simply." Use plain connectors: also, and, but, however, still. + +21. **No AI verbs.** Banned: delve, leverage, utilize, facilitate, foster, bolster, underscore, unveil, navigate (metaphorical), streamline, endeavour, ascertain, elucidate. Use their plain equivalents: explore, use, help, encourage, strengthen, highlight, reveal, manage, simplify, try, find out, explain. + +22. **No academic AI tells.** Banned: "shed light on", "pave the way for", "a myriad of", "a plethora of", "paramount", "pertaining to", "prior to" (use "before"), "subsequent to" (use "after"), "in light of" (use "because of"), "with respect to" (use "about"), "in terms of" (use "about" or "for"), "the fact that" (rewrite the sentence). + +23. **Quote sources accurately, and set off the long ones.** When you put text in quotation marks and attribute it to a source, every word must match the source exactly. Do not correct grammar, change plural to singular, swap pronouns, or clean up the wording. If you must alter a quote for clarity, mark the change with square brackets. If the wording is awkward, paraphrase without quotation marks instead. Name the speaker and the medium when you introduce a quote. Keep short quotes run-in inside the sentence. Set off a long quotation (more than about fifteen words) as its own indented block, introduced by a one-sentence attribution clause, so the source's voice is visually distinct from yours. + +24. **No research-process narration.** Report the facts you can support and silently omit what you cannot. Do not narrate what you searched for and failed to find ("could not be located", "was not found", "is not available", "no record was found"). Do not attach an "as of [date]" qualifier to your own inability to find something. Do not write sections or lists enumerating the documents or facts you could not obtain. Do not add meta-commentary about how the text was put together. If a fact cannot be supported, delete it. Do not tell the reader you looked. + +Banned-word lists: `ai-writing-detection.md` in this directory. diff --git a/.agents/skills/nomad-pages/SKILL.md b/.agents/skills/nomad-pages/SKILL.md new file mode 100644 index 00000000..612febf7 --- /dev/null +++ b/.agents/skills/nomad-pages/SKILL.md @@ -0,0 +1,52 @@ +--- +name: nomad-pages +description: NomadNet page browsing and Mesh Server page nodes (nomadnetwork.node, Micron, Markdown). Use when changing nomad routes, page_node manager, WS download, or allowed page formats. +--- + +# Skill: nomad-pages + +NomadNet pages are Reticulum destinations with aspect `nomadnetwork.node`. MeshChatX browses remote nodes and can host local page nodes (Tools, Mesh Server). Local HTTPS is the control plane for this device. Remote nodes are not REST clients of MeshChatX. + +User docs: `docs/en/nomad-network.md`, `docs/en/nomadmesh-pages.md`. + +## When to use + +- Nomad browser UI, downloads, or archives +- Page node create/start/stop, file upload, request handlers +- Micron (`.mu`), Markdown, plain text, or sanitised HTML rendering +- WS types that fetch or cache remote pages + +Generic RNS Link transport for non-Nomad apps is `rns-link-api`, not this skill. + +## Hosted nodes + +- Manager: `meshchatx/src/backend/page_node_manager.py` +- Destination: `meshchatx/src/backend/page_node.py` (`APP_NAME = "nomadnetwork"`) +- Storage: `storage/identities//page_nodes//` +- HTTP: `meshchatx/src/backend/http/routes/page_nodes.py` +- Browse/download HTTP: `meshchatx/src/backend/http/routes/nomad.py` +- WS: `meshchatx/src/backend/http/ws/handlers_nomad.py` + +Page-node files are a path jail. Follow `path-jail-local-fs`. The Mesh Server rejects disallowed extensions on upload (see NomadNet page formats). + +## Formats + +| Extension | Role | +| --- | --- | +| `.mu` | Micron markup (NomadNet default) | +| `.md` | Markdown | +| `.txt` | Plain text | +| HTML | Sanitised. Do not widen the sanitiser to run scripts. | + +Announce display names parse through `parse_nomadnetwork_node_display_name`. Store toggles: `announce_store_nomadnetwork_node` in `announce_manager.py`. + +## Gates + +1. Address nodes by destination hash, not IP. +2. Downloads and WS mutators require an authenticated session when password auth is enabled (`auth-csrf-ws-security`). +3. Privacy mode blocks clearnet helpers around Nomad. Mesh page fetch over RNS stays allowed (`privacy-mode-clearnet`). +4. Tear down hosted destinations on identity switch. + +## Verification + +Prefer focused backend tests next to existing page-node / nomad tests, plus frontend tests when the browser UI changes. diff --git a/docs/agents/skills/page-toast-tests/SKILL.md b/.agents/skills/page-toast-tests/SKILL.md similarity index 96% rename from docs/agents/skills/page-toast-tests/SKILL.md rename to .agents/skills/page-toast-tests/SKILL.md index 391cd97a..586fb69a 100644 --- a/docs/agents/skills/page-toast-tests/SKILL.md +++ b/.agents/skills/page-toast-tests/SKILL.md @@ -1,3 +1,8 @@ +--- +name: page-toast-tests +description: New MeshChatX pages with routes, nav, toasts, i18n, and tests. Use when adding a page or wiring ToastUtils and locale keys. +--- + # Skill: page-toast-tests New MeshChatX pages with routes, nav, toasts, i18n, and tests. diff --git a/docs/agents/skills/page-toast-tests/examples.md b/.agents/skills/page-toast-tests/examples.md similarity index 100% rename from docs/agents/skills/page-toast-tests/examples.md rename to .agents/skills/page-toast-tests/examples.md diff --git a/docs/agents/skills/path-jail-local-fs/SKILL.md b/.agents/skills/path-jail-local-fs/SKILL.md similarity index 93% rename from docs/agents/skills/path-jail-local-fs/SKILL.md rename to .agents/skills/path-jail-local-fs/SKILL.md index 1ac5765a..0d6948d7 100644 --- a/docs/agents/skills/path-jail-local-fs/SKILL.md +++ b/.agents/skills/path-jail-local-fs/SKILL.md @@ -1,3 +1,8 @@ +--- +name: path-jail-local-fs +description: Local file browse/upload/download/delete with a hard path jail, CSRF-safe mutators, and oracle tests. Use when any handler takes a client path and touches disk. +--- + # Skill: path-jail-local-fs Add or change local filesystem features (browse, upload, download, mkdir, delete) with a hard path jail, CSRF-safe mutators, and oracle-style tests. Do not ship file CRUD that can escape identity or feature roots. @@ -11,10 +16,10 @@ Add or change local filesystem features (browse, upload, download, mkdir, delete Also read: -- `docs/agents/conventions/path-jail.md` -- `docs/agents/skills/auth-csrf-ws-security/SKILL.md` -- `docs/agents/skills/test-oracles/SKILL.md` -- `docs/agents/skills/page-toast-tests/SKILL.md` when adding UI +- `.agents/conventions/path-jail.md` +- `.agents/skills/auth-csrf-ws-security/SKILL.md` +- `.agents/skills/test-oracles/SKILL.md` +- `.agents/skills/page-toast-tests/SKILL.md` when adding UI ## Threat model (assume without asking) diff --git a/docs/agents/skills/plugin-install-security/SKILL.md b/.agents/skills/plugin-install-security/SKILL.md similarity index 92% rename from docs/agents/skills/plugin-install-security/SKILL.md rename to .agents/skills/plugin-install-security/SKILL.md index fd7cd39b..ce1f289b 100644 --- a/docs/agents/skills/plugin-install-security/SKILL.md +++ b/.agents/skills/plugin-install-security/SKILL.md @@ -1,3 +1,8 @@ +--- +name: plugin-install-security +description: Plugin install, RSG signatures, permissions, WASM/Python/Sideband runtimes. Use when changing install/enable/invoke or adding KNOWN_HOOKS / KNOWN_MANAGERS. +--- + # Skill: plugin-install-security Install, sign, permission-grant, and sandbox plugins without bypassing RSG, integrity, or runtime guards. diff --git a/.agents/skills/privacy-mode-clearnet/SKILL.md b/.agents/skills/privacy-mode-clearnet/SKILL.md new file mode 100644 index 00000000..e717fef7 --- /dev/null +++ b/.agents/skills/privacy-mode-clearnet/SKILL.md @@ -0,0 +1,38 @@ +--- +name: privacy-mode-clearnet +description: Privacy mode blocks backend outbound HTTP/HTTPS and tightens CSP. It does not stop Reticulum mesh traffic. Use when adding clearnet fetches, translators, community lists, docs download, or CSP changes. +--- + +# Skill: privacy-mode-clearnet + +`privacy_mode_enabled` is a config flag. When it is on, server-side HTTP/HTTPS from MeshChatX app features must fail closed. LXMF, LXST, RRC, announces, and other RNS traffic keep running. + +## When to use + +- Translator, GIF search, community interface lists, docs fetch, repository download, or any new `urllib`/`aiohttp`/`requests` call +- CSP or outbound-allow changes +- A feature that "just needs to hit GitHub/PyPI once" + +## Mechanism + +`meshchatx/src/backend/privacy_mode.py`: + +- `privacy_mode_enabled(config)` reads `config.privacy_mode_enabled` +- `ensure_outbound_http_allowed(config, feature=...)` raises `OutboundHttpBlockedError` when the flag is on + +Call `ensure_outbound_http_allowed` at the start of every backend path that would open a clearnet socket. Map `OutboundHttpBlockedError` to HTTP 403 or a structured `{ok: false}` the UI already handles. Do not swallow it and retry. + +Config key: `privacy_mode_enabled` in `config_manager.py`. Settings copy lives under `app.privacy_mode_*` locale keys. + +## What privacy mode is not + +- Not a mesh kill switch +- Not Landlock (filesystem sandbox). See `landlock-sqlite`. +- Not `--no-https` (local UI TLS) +- Not plugin `network:fetch` grants. Plugins still need declared permissions even when privacy mode is off. See `plugin-install-security`. + +Optional clearnet helpers (docs fetch, community interface lists) stay behind this flag and explicit settings. Core messaging, identity, and pathfinding must work with privacy mode on. + +## Tests + +When you add a clearnet call, add a test that enables privacy mode and asserts the call is blocked (`OutboundHttpBlockedError` or the HTTP status the route already uses). Search existing tests for `privacy_mode` and match that pattern. diff --git a/docs/agents/skills/reticulum-design-gates/SKILL.md b/.agents/skills/reticulum-design-gates/SKILL.md similarity index 91% rename from docs/agents/skills/reticulum-design-gates/SKILL.md rename to .agents/skills/reticulum-design-gates/SKILL.md index 9a8167cf..d3538e0d 100644 --- a/docs/agents/skills/reticulum-design-gates/SKILL.md +++ b/.agents/skills/reticulum-design-gates/SKILL.md @@ -1,3 +1,8 @@ +--- +name: reticulum-design-gates +description: Mesh design review against Zen of Reticulum and MeshChatX architecture. Use before any feature that sends, receives, discovers, or stores mesh data. +--- + # Skill: reticulum-design-gates Stop IP-era and cloud-era design mistakes before they land in MeshChatX. @@ -11,7 +16,7 @@ Grounded in the [Zen of Reticulum](https://reticulum.network/manual/zen.html) an - Bug-report / telemetry / logging paths that might leak identity material - "Quick" integrations that want HTTP, DNS, Firebase, or a central API "just for sync" -Also read: `docs/agents/conventions/reticulum-zen.md`, `docs/agents/overview.md`, `docs/en/architecture.md`. +Also read: `.agents/conventions/reticulum-zen.md`, `.agents/skills/reticulum-stack/SKILL.md`, `.agents/overview.md`, `docs/en/architecture.md`. ## Gate 0: Intent @@ -93,8 +98,9 @@ Allowed: ## Key references - https://reticulum.network/manual/zen.html -- `docs/agents/conventions/reticulum-zen.md` -- `docs/agents/overview.md` +- `.agents/conventions/reticulum-zen.md` +- `.agents/skills/reticulum-stack/SKILL.md` +- `.agents/overview.md` - `docs/en/architecture.md` - `docs/en/messaging.md` - `docs/en/rns-link-api.md` diff --git a/.agents/skills/reticulum-interfaces/SKILL.md b/.agents/skills/reticulum-interfaces/SKILL.md new file mode 100644 index 00000000..6ee62556 --- /dev/null +++ b/.agents/skills/reticulum-interfaces/SKILL.md @@ -0,0 +1,46 @@ +--- +name: reticulum-interfaces +description: Reticulum interfaces as clothing. Use when editing interface config, RNode/TCP/AutoInterface, interface modes, location_cmd, or any feature that special-cases WiFi vs LoRa vs TCP in application code. +--- + +# Skill: reticulum-interfaces + +Application code talks to destinations and aspects. Interfaces are how this node touches the physical or overlay medium. Do not put WiFi vs LoRa vs TCP branches in message send, call setup, or announce handlers. + +Config lives with Reticulum (`~/.reticulum` by default), not only in the identity SQLite database. MeshChatX edits that config through the interface editor and HTTP routes. + +## When to use + +- Interfaces page, add-interface forms, stats, or discovery +- RNode serial/TCP/BLE, AutoInterface, TCPClient/TCPServer, I2P, or similar +- `location_cmd` or other subprocess fields in interface config +- A feature that wants to "detect LoRa and send smaller packets in the manager" + +Packet size and delay belong in protocol design (stamps, attachments, RNCP, PTT), not in `if interface_type == "RNode"`. + +## MeshChatX editor rules + +`meshchatx/src/backend/interface_editor.py`: + +- Allowed modes: `full`, `gateway` (`gw`), `access_point` (`ap` / `accesspoint`), `pointtopoint` (`ptp`), `roaming`, `boundary`, `internal`. Prefer the long form when writing config. +- RNode `tcp://host:port` must store `tcp://` only. Reticulum's TCPConnection calls `socket.getaddrinfo(target_host, 7633)`. An embedded `:port` breaks resolution. +- `location_cmd` is executed by RNS Discovery via `subprocess.run([path])`. Reject shell metacharacters and relative traversal before persisting (`_LOCATION_CMD_FORBIDDEN`). +- Under Landlock, `location_cmd` binaries outside allowed read roots fail with `Permission denied`. Widen `landlock_sandbox.py` on purpose or document `MESHCHAT_LANDLOCK=0` for debugging. See `landlock-sqlite`. + +## HTTP and UI + +- Routes: `meshchatx/src/backend/http/routes/interfaces.py` +- UI: `meshchatx/src/frontend/components/interfaces/` +- Ownership: `.agents/module-ownership.md` (Interfaces row) + +Do not add a WebSocket mutator that writes interface config. CSRF-protected HTTP via `window.api`. + +## Tests + +Interface stats and editor tests under `tests/backend/` (names in the ownership table). After RNode TCP or `location_cmd` changes, add a focused case next to the existing editor tests. + +## Related + +- `reticulum-stack` for destination/aspect addressing +- `reticulum-design-gates` before shipping medium-specific behaviour +- `android-webview-bridge` for RNode USB/BLE on Android (jnius shim, usb4a, Able BLE, native flasher) diff --git a/.agents/skills/reticulum-stack/SKILL.md b/.agents/skills/reticulum-stack/SKILL.md new file mode 100644 index 00000000..7e78785b --- /dev/null +++ b/.agents/skills/reticulum-stack/SKILL.md @@ -0,0 +1,76 @@ +--- +name: reticulum-stack +description: Reticulum identities, destination hashes, aspects, announces, path requests, and links as used in MeshChatX. Use when addressing peers, adding a mesh app aspect, storing announces, or requesting a path. +--- + +# Skill: reticulum-stack + +Reticulum is a cryptography-based networking stack for local and wide-area networks, including high-latency and low-bandwidth links. MeshChatX is a client on that stack. It is not a REST mesh and not an IP overlay with extra steps. + +Site: [reticulum.network](https://reticulum.network/). +Philosophy: [Zen of Reticulum](https://reticulum.network/manual/zen.html). +Gates: `reticulum-design-gates`. Interfaces: `reticulum-interfaces`. + +## When to use + +- Addressing a peer, storing a favourite, or opening a path +- Adding or changing a destination aspect +- Announce ingest, display names, or path-table behaviour +- Anything that looks like "we need a server / DNS / hostname to find people" + +## Facts that do not move + +From the Reticulum manual and [reticulum.network](https://reticulum.network/): + +- Packets do not carry a source address. +- There is no central address registry. Anyone can allocate destination hashes from an identity key. +- An address is a hash of an identity, not a location. Move the key, keep the hash. +- Newly generated destinations become reachable after announce and path discovery (seconds to a few minutes on a working mesh). +- Encryption is on by default. Keys are ephemeral. Forward secrecy is the default. +- Unencrypted links cannot be established. Unencrypted packets to a destination are dropped as invalid. + +MeshChatX mapping: + +- Cryptographic identity lives under `storage/identities//identity`. +- Display names are local labels on that hash. They are not network addresses. +- Shared Reticulum config is `~/.reticulum` unless `--reticulum-config-dir` / `MESHCHAT_RETICULUM_CONFIG_DIR` / `MESHCHAT_DATA_DIR` overrides it. +- Identity switch does not reset `~/.reticulum`. + +## Destination plus aspect + +Address peers as destination hash + aspect. Do not store `host:port` as the mesh address. + +Aspects MeshChatX already uses: + +| Aspect | Meaning | +| --- | --- | +| `lxmf.delivery` | LXMF mail | +| `lxmf.propagation` | Propagation node | +| `lxst.telephony` | LXST calls | +| `nomadnetwork.node` | NomadNet page server | +| `rrc.hub` | Relay Chat hub | + +Custom apps get their own aspect (example from design gates: `mcx-bugs-v1`). Do not overload `lxmf.delivery` for non-mail traffic. RNS Link API aspects are dot-separated app name plus sub-aspects (example `microrn.mgmt`). + +Announce ingest caps and store toggles live in `announce_manager.py` (`announce_max_stored_*`, `announce_store_*`, `announce_fetch_limit_*`). + +## Path and delay + +Missing path: request a path, allow LXMF propagate where that is the protocol, show a recoverable outbound state. Do not spin the UI until an ACK arrives on a LoRa-class link. + +Links are live sessions on top of paths. LXST calls and RRC hubs use links. LXMF mail is store-and-forward and must survive a missing path. + +## Key files + +- `meshchatx/src/backend/identity_context.py` +- `meshchatx/src/backend/identity_manager.py` +- `meshchatx/src/backend/announce_manager.py` +- `docs/en/identity-and-security.md` +- `docs/en/architecture.md` + +## Refuse + +- Required `fetch(https://...)` to deliver LXMF or discover peers +- New global name registry or "default discovery server" for core reachability +- Treating the local HTTPS UI as the mesh +- Logging private keys or unredacted identity material by default diff --git a/.agents/skills/rns-filesync/SKILL.md b/.agents/skills/rns-filesync/SKILL.md new file mode 100644 index 00000000..7b7e0649 --- /dev/null +++ b/.agents/skills/rns-filesync/SKILL.md @@ -0,0 +1,43 @@ +--- +name: rns-filesync +description: RNS FileSync shares, announces, permissions, and sync-root path jail. Use when changing the filesync handler, HTTP routes, announce interval, or in-app sync-tree CRUD. +--- + +# Skill: rns-filesync + +Identity-scoped wrapper around vendored `rns_filesync.FileSyncService`. Peers are destination hashes. The sync directory is a path jail, not a convenient view of the host disk. + +## When to use + +- FileSync pages, share announce, peer permissions, or transfer status +- In-app browse/upload/mkdir/delete under the sync root +- Announce interval or service start/stop +- Anything that joins a client-supplied path onto the sync directory + +Path jail details: `path-jail-local-fs` and `.agents/conventions/path-jail.md`. +Reference resolve helper: `rns_filesync_handler.py` (`_resolve_manager_path`). + +## Hard rules + +1. Jail CRUD to the configured `sync_directory` only. The folder picker that *chooses* a sync root is a different, looser jail (identity storage with reserved tops blocked). Do not reuse the picker jail for tree/upload/delete. +2. Skip and refuse mutation of protocol sidecars (`.rns-filesync*`, `.rns-xfer*`). +3. `announce_interval` must be an integer `>= 10` seconds. Invalid values return `{"ok": False, "error": ...}` rather than throwing 500. +4. Upload cap for in-app manager uploads is `MANAGER_UPLOAD_MAX_BYTES` (64 MiB). That cap is the local control plane, not a mesh payload budget. +5. Large mesh transfers stay on FileSync/RNCP. Do not stuff files into LXMF chat fields. +6. Identity-scoped. Switching identities must tear down the service (see `identity-switch-teardown`). + +## Key files + +| Area | Path | +| --- | --- | +| Handler | `meshchatx/src/backend/rns_filesync_handler.py` | +| HTTP | `meshchatx/src/backend/http/routes/filesync.py` | +| Vendored service | `vendor/rns_filesync/` | +| UI | `meshchatx/src/frontend/components/filesync/` | +| Oracle tests | `tests/backend/test_rns_filesync_security.py`, `tests/backend/test_path_jail_oracles.py` | + +## Verification + +```bash +uv run pytest tests/backend/test_rns_filesync_security.py tests/backend/test_path_jail_oracles.py -q --tb=short +``` diff --git a/docs/agents/skills/rns-link-api/SKILL.md b/.agents/skills/rns-link-api/SKILL.md similarity index 91% rename from docs/agents/skills/rns-link-api/SKILL.md rename to .agents/skills/rns-link-api/SKILL.md index 6ac819bf..c5c0a97b 100644 --- a/docs/agents/skills/rns-link-api/SKILL.md +++ b/.agents/skills/rns-link-api/SKILL.md @@ -1,3 +1,8 @@ +--- +name: rns-link-api +description: Generic RNS Link WebSocket transport and plugin rnsLink.* managers. Use when changing rns.link.* handlers, link cache, or plugin link permissions. +--- + # Skill: rns-link-api Implement or consume the generic RNS Link WebSocket transport and plugin manager capabilities without breaking auth, caching, or disconnect cleanup. diff --git a/.agents/skills/rossmann-voice/SKILL.md b/.agents/skills/rossmann-voice/SKILL.md new file mode 100644 index 00000000..09465ef2 --- /dev/null +++ b/.agents/skills/rossmann-voice/SKILL.md @@ -0,0 +1,172 @@ +--- +name: rossmann-voice +description: "Louis Rossmann's writing voice for general prose: testable-number density, high sentence-length variance, claim-then-proof structure, contractions, contempt shown through precision. Consult when writing in his voice." +--- + +# Rossmann Voice Profile + +This profile is data-driven, built from corpus analysis of 513,683 words of Louis Rossmann's writing (5,632 entries, 2014-2026). The examples below are repair-themed because that is what the corpus is about, but the voice applies to any subject: the traits are structural, not topical. Write about cooking, software, or tax policy in this voice and the same rules hold. + +## Core Principle + +The writing is identifiable because every claim carries a testable number. Dollar amounts appear at 32.0 per 10,000 words and legal or technical terms at 18.4 per 10,000 words; combined, that is roughly one specific, verifiable reference per 200 words. Preserve this density: every paragraph earns its place by containing a dollar amount, a part identifier, a named source, a date, or a measurable quantity that a reader could check. Contempt for a bad practice is expressed through the precision of the description, not through adjectives or editorial commentary. + +## Sentence-Level Rules + +1. **Ground every claim in a testable number.** Every paragraph that describes a practice, cost, or restriction must contain at least one specific number. (Corpus: 32.0 dollar amounts per 10k words; bigrams include "repair bill" (52), "million dollars" (32), "ten years" (52).) + - WRONG: "Repair costs are often unreasonably high compared to the actual parts needed." + - RIGHT: "Motherboard-level repairs at independent shops ran $250 to $425 until parts dried up. Donor boards now cost $200 to $400 per unit." + +2. **Name the component, the supplier, and the price.** When describing a restriction or a cost disparity, name the specific part, the company that makes it, and the actual or claimed price. (Corpus: "board" (452), "parts" (398), "battery" (294), "screen" (285); bigrams: "board repair" (143), "charge port" (47), "liquid damage" (69).) + - WRONG: "A common issue with these laptops is a power delivery problem." + - RIGHT: "Apple's supply agreements with chipmakers such as Intersil & Texas Instruments bar those companies from selling ICs like the ISL9240 power management chip to independent repair providers." + +3. **Frame restrictions as concrete operations, not abstract policy.** Name the mechanism: which supplier was told not to sell, which contract clause prohibits the action, which firmware function executes the lock. (Corpus: "business" (897), "work" (1,016), "parts" (398); bigrams: "repair shop/shops" (124/107), "third party" (54).) + - WRONG: "Independent repair shops face economic challenges due to manufacturer restrictions." + - RIGHT: "Independent shops can't order OEM batteries or screens from Samsung SDI or LG Display because Apple's supply contracts bar those makers from selling to unauthorized buyers." + +4. **Maintain high sentence-length variance.** Mix sentences of 4 to 10 words with sentences of 25 to 36 words. Do not write three consecutive sentences of similar length. (Corpus: mean 18.34 words, median 15, std dev 15.27; p10=4.0, p90=36.0; 10.8% of sentences are fragments under 5 words.) + - WRONG: "The practice of planned obsolescence, whereby manufacturers design products to fail after a predetermined period, has been a growing concern among consumer advocates who believe that this approach prioritizes profits over durability." + - RIGHT: "Replacing the iPhone 6 charge port flex cable requires no soldering. The repair takes five minutes. Apple Authorized Service Providers quoted full-device replacements for this failure, telling customers the port was soldered to the logic board." + +5. **Use contractions by default; expand for emphasis.** Use "can't", "doesn't", "isn't" in standard prose. Reserve "did not" or "does not" for formal description or when the negative needs to land with force. (Corpus: contraction rate 83.6%, stable at 77 to 89% across years.) + - WRONG (stiff): "The manufacturer does not sell replacement LCDs independently. The buyer does not have the option to purchase only the panel." + - RIGHT: "The manufacturer doesn't sell replacement LCDs on their own; the buyer must take the full display assembly, frame, hinges, and webcam included. Apple did not disclose this bundling anywhere in its self-service repair documentation." + +6. **Quantify expertise through volume, not adjectives.** Do not call someone "experienced" or "skilled". State how many times they did the thing, how many units they examined, or how many years they have logged. (Corpus: "at least 1000 times" (personal), "at least 10,000 times" (team), "30-50 walk-in customers for 15 years.") + - WRONG: "A skilled technician can perform this repair efficiently." + - RIGHT: "Rossmann Repair Group has documented the MacBook Pro display adhesive separation over 10,000 times across its technicians." + +7. **Weave specifics into the sentence flow.** Build the supporting detail into the active prose so it reads as part of the argument, not a footnote dump. (Corpus: legal-citation density roughly doubled from 8.8/10k words in 2016 to 20+/10k in 2020-2025.) + - WRONG: "The Magnuson-Moss Warranty Act protects consumers." + - RIGHT: "The Magnuson-Moss Warranty Act (15 U.S.C. ch. 50, sections 2301 through 2312) bars manufacturers from tying warranty coverage to the use of a specific service provider or brand of replacement part." + +8. **Use exact identifiers.** Do not write "copyright law" when you mean "17 U.S.C. section 1201". Do not write "software updates" when you mean "over-the-air updates to closed-source firmware". The specific name is always stronger than the category. + - WRONG: "Federal law prevents people from bypassing digital locks on their devices." + - RIGHT: "17 U.S.C. section 1201 makes it a federal offense to bypass a technical protection measure on a digital device, even to repair it." + +9. **Use "&" instead of "and".** This is a genuine trait of Rossmann's writing: he uses ampersands at a rate of 1 per 7 uses of "and" (1,362 ampersands against 8,508 "and" tokens). Use "&" as the default conjunction in new prose. Exceptions: do not use "&" to start a sentence, and preserve "and" inside direct quotations. + - WRONG: "Apple restricts repairs and replacements through parts pairing." + - RIGHT: "Apple restricts repairs & replacements through parts pairing." + +## Paragraph Structure Rules + +1. **Open with a claim, then prove it.** Start paragraphs with a direct assertion, not a topic sentence or a transition. The assertion commits to a position; supporting detail follows in the next 1 to 2 sentences. (Corpus: entry-opening words are "I" (22.7%), "this" (3.9%), "it's" (3.0%). Only 0.8% of entries open with "in", a transition-style opener. Rossmann opens with claims, not context.) + +2. **Keep paragraphs to 2 to 3 sentences.** A dense factual sentence followed by 1 to 2 sentences of context or consequence. Do not exceed 5 sentences per paragraph. (Corpus: average paragraph length 2.1 sentences, median 2.0.) + +3. **Prose over lists for argument.** Reserve bullet or numbered lists for timelines, specification comparisons, or lists of affected items. All argument and analysis goes in prose paragraphs. (Corpus: only 1.4% of entries use structured lists. Rossmann prefers inline enumeration: "from tractors, to consumer electronics, to medical devices and cars.") + +4. **Alternate paragraph weight.** Follow a dense, detail-heavy paragraph with a shorter one (2 sentences) that states a single consequence or outcome. + +5. **Incident paragraphs follow: action, mechanism, impact.** First sentence: what was done. Second: how it works. Third: what happened to the person or the market as a result. + +## Voice Drift Prevention + +LLMs revert to "average internet tone" over long outputs, producing progressively smoother, more generic prose. This voice is the opposite of smooth; it is jagged, with high sentence-length variance, specific numbers, and direct claims. Watch for these drift signals: + +**Signs the voice is drifting:** +- Consecutive sentences within 3 words of each other in length. The voice should alternate short and punchy with long and analytical. +- Paragraphs that lack a dollar amount, a named thing, or a measurable quantity. The voice averages one per 200 words. +- Contractions disappearing. The mature voice runs 80%+ contractions; "does not" four times in a paragraph is drift. +- Opening sentences that set context instead of making a claim. "There are several factors..." is drift; "Apple charges $1,200 for..." is the voice. + +**How to correct mid-piece:** +- After each section, re-read the DO/DON'T table below and check the section matches the RIGHT column. +- Check sentence-length variance within each paragraph: at least one sentence under 10 words and one over 20 words per 3-paragraph block. +- If a passage could appear on any generic site, it has drifted. Rewrite with the specific part, price, date, or documented detail that makes it unique. + +## Argumentation Pattern + +Rossmann argues using a **Claim-Mechanism-Reality** structure. This is data-confirmed: 21.5% of entries (1,212 of 5,632) use interleaved quote blocks to quote an opponent and take the claim apart, averaging 1.39 quotes per quoting entry. + +1. **State the opponent's position**, with attribution to a real source. +2. **Present the documented contradiction**, with the technical or factual evidence. +3. **State the documented outcome**, with a real source. + +**Supporting patterns (from the corpus):** + +- **Cite the opponent's own documentation against them.** Prefer the other side's internal documents, testimony, or filings over third-party criticism. (Corpus: Apple's internal documentation showed the iPhone 6 was "7x more likely to bend than prior iPhones".) + +- **Show advocacy against self-interest.** When presenting Rossmann's positions, include the cases where his position would cost him money. (Corpus: "if Apple did what I was advocating, this would have a direct negative impact on the revenue of my repair business... I cannot compete with free. I push for this anyway.") + +- **Acknowledge the valid criticism before extending the argument.** Include the strongest fair counterpoint before the response. This appears more in his mature writing (2020+). (Corpus: "The criticism that would be valid is that the laws that got passed have not tangibly changed anything for repair shops or end consumers.") + +- **Use analogies that apply the opponent's logic to everyday life.** Take a justification for the practice and apply it to a commonplace activity. Keep the analogy to one sentence. (Corpus: "By your standard, every restaurant that passes a health inspection is fascism, plumbers having licenses is fascism.") + +## Vocabulary Guide + +Use plain, mechanical language. These substitutions trade vague terms for precise ones: + +| Instead of | Use | +|---|---| +| device ecosystem | product line | +| consumer-facing | sold to consumers | +| end-of-life (euphemism) | discontinued support for | +| intellectual property protections | copyright restrictions, patent claims, or trade secret claims (be specific) | +| aftermarket components | third-party parts, or non-OEM parts | +| unauthorized repair | independent repair | +| tamper-proof | designed to prevent owner access | +| brick (casual) | render non-functional | +| void your warranty | condition warranty coverage on | +| take action | file suit, issue a cease-and-desist, lobby against (be specific) | +| stakeholders | name them: owners, repair shops, manufacturers, legislators | +| safety concerns | name the specific claimed hazard | +| experienced technician | state the repair count or years of operation | +| many issues / various problems | state the count or name the specific issues | + +**Rossmann-characteristic vocabulary (from corpus top content words):** +- Repair domain: "repair" (1,879), "board" (452), "parts" (398), "battery" (294), "screen" (285) +- Business domain: "business" (897), "money" (793), "customer/customers" (395/450), "store" (381) +- Use "physical property" when discussing ownership rights (not "device" or "product") +- Use "closed-source firmware" when specificity matters (not "software") +- Use "reverse engineer" for repair investigation (not "examine" or "look into") +- Use "component-level repair" to distinguish from board-level or device-level replacement + +## What This Voice Is NOT + +Some genuine Rossmann traits do not transfer to clean third-person prose. Each has a translation: + +- **First-person pronouns** ("I", "we", "my"): his #1 sentence-opening word is "I" at 20.6% of sentences. For neutral prose, translate to third-person while keeping the experiential specificity. "I have done this repair 1,000 times" becomes "Rossmann has documented this repair on over 1,000 units." (Keep first person when the piece is genuinely his own first-person essay or script.) +- **Profanity**: 27.2 per 10k words overall, declining from 54.8/10k (2016) to 14.7/10k (2024). Remove it for neutral prose. The equivalent is a documented juxtaposition of claim against reality. +- **Rhetorical questions**: 4.3% of sentences overall, down to 2.2% by 2024-2026. Convert to declarative statements. +- **ALL CAPS emphasis**: 4.45 per 1k words. Translate to bold text or to specific, named emphasis. +- **Ellipses**: 1.76 per 1k words. Cut them; trailing-off doesn't suit clean prose. +- **Ampersands**: kept. Use "&" in new prose (see Sentence-Level Rule 9). + +## DO / DON'T Quick Reference + +| Instead of (generic/AI) | Write (Rossmann voice) | +|---|---| +| Apple limits repairs to ensure user safety and security. | Apple restricts component replacement through firmware-level parts pairing that disables hardware functions when a non-paired part is detected. | +| Repair costs are unreasonably high. | Apple quoted $755 for a backlight repair on a 2018 MacBook Pro. The failed part was a 50-cent filter. | +| Software updates can cause older devices to slow down. | Apple released iOS 10.2.1 in January 2017, which throttled CPU clock speeds on iPhone 6, 6S, 7, and SE models with degraded batteries without disclosing the change. | +| The company faced criticism for its repair policies. | Apple's Authorized Service Provider agreement requires participating shops to return replaced parts and bars them from sourcing parts on their own. | +| Independent repair shops face many challenges. | Independent shops can't order OEM batteries or screens from Samsung SDI or LG Display because Apple's supply contracts bar those makers from selling to unauthorized buyers. | +| Component-level repair is cheaper than board replacement. | Replacing the failed ISL9240 chip costs $4 in parts & 45 minutes of labor. Apple quoted $1,200 for a logic board replacement on the same machine. | +| Right to repair is a movement advocating for the ability to fix electronics. | Right-to-repair legislation would remove federal & state restrictions that criminalize bypassing technical protection measures on hardware the buyer owns. | +| Courts have said people can record public officials. | In *Borreca v. Fasi*, 369 F. Supp. 906 (D. Haw. 1974), the court ruled that government officials can't selectively exclude individuals from public proceedings open to the press. | +| Manufacturers use software to prevent independent repair. | Manufacturers push over-the-air updates to closed-source firmware that disable hardware functions after a non-authorized part is detected. | +| The warranty was voided unfairly. | The manufacturer conditioned warranty coverage on the use of its own service network, violating the Magnuson-Moss Warranty Act (15 U.S.C. sections 2301 through 2312). | +| A skilled technician can perform this repair efficiently. | Rossmann Repair Group has documented this repair over 10,000 times across its technicians. It takes five minutes with no soldering. | +| The FTC is looking into changing rules regarding warranties. | In July 2021, the FTC voted 5-0 to prioritize enforcement of the Magnuson-Moss Warranty Act against manufacturers that tie warranty coverage to branded parts. | +| Companies should be more transparent about their practices. | Apple didn't disclose that iOS 10.2.1 throttled processor performance until December 2017, eleven months after the update shipped, and only after Geekbench benchmarks confirmed the slowdown. | +| Lobbyists often influence government policy on tech issues. | Apple, John Deere, & the Consumer Technology Association submitted written testimony opposing every state right-to-repair bill introduced between 2015 and 2023. | +| "repairs and replacements" | "repairs & replacements" | +| (Four consecutive sentences of 14-17 words each) | Mix: "The repair takes five minutes." (5 words) then "Apple Authorized Service Providers quoted full-device replacements for this failure, telling customers the port was soldered to the logic board." (21 words) | + +## Statistical Fingerprint + +These measurements define the quantitative profile of the writing (corpus: 513,683 words, 28,005 sentences, 5,632 entries, 2014-2026): + +| Metric | Measured Value | +|---|---| +| Median sentence length | 15 words (mean 18.34, std dev 15.27) | +| Dollar amount density | 32.0 per 10,000 words (about 1 dollar figure every 312 words) | +| Legal/technical term density | 18.4 per 10,000 words (doubled from 8.8 in 2016 to 20+ in 2020-2025) | +| Contraction rate | 83.6% (stable at 77 to 89% across all years) | +| Question-to-statement ratio | 4.3% overall; 2.2% in the mature voice (2024-2026) | +| Average paragraph length | 2.1 sentences (median 2.0) | +| Quote-response frequency | 21.5% of entries (1,212 of 5,632) use interleaved quote blocks | + +**Target for new prose (modeling the 2020+ mature voice):** sentences averaging 18 to 22 words with high variance, specific identifiers woven into the prose, contractions at 80%+, questions under 3%, no profanity, no rhetorical questions. The mature voice is longer-sentenced, more precise, and more declarative than his early (2014-2016) writing. diff --git a/docs/agents/skills/rrc-relay-chat/SKILL.md b/.agents/skills/rrc-relay-chat/SKILL.md similarity index 94% rename from docs/agents/skills/rrc-relay-chat/SKILL.md rename to .agents/skills/rrc-relay-chat/SKILL.md index 68464002..c7f4b7df 100644 --- a/docs/agents/skills/rrc-relay-chat/SKILL.md +++ b/.agents/skills/rrc-relay-chat/SKILL.md @@ -1,3 +1,8 @@ +--- +name: rrc-relay-chat +description: Reticulum Relay Chat hubs, rooms, +k keys, moderation, client state. Use when changing RRC protocol, hub hosting, or Relay Chat UI. +--- + # Skill: rrc-relay-chat Implement or harden Reticulum Relay Chat (RRC) hubs and clients without breaking membership, +k keys, or identity scoping. diff --git a/docs/agents/skills/test-loop/SKILL.md b/.agents/skills/test-loop/SKILL.md similarity index 90% rename from docs/agents/skills/test-loop/SKILL.md rename to .agents/skills/test-loop/SKILL.md index 2056f3fa..a99a5165 100644 --- a/docs/agents/skills/test-loop/SKILL.md +++ b/.agents/skills/test-loop/SKILL.md @@ -1,3 +1,8 @@ +--- +name: test-loop +description: Focused verification with task/uv/pnpm without hanging shells. Use when running tests in an agent loop. +--- + # Skill: test-loop Focused verification with task/uv/pnpm without hanging shells. diff --git a/docs/agents/skills/test-oracles/SKILL.md b/.agents/skills/test-oracles/SKILL.md similarity index 88% rename from docs/agents/skills/test-oracles/SKILL.md rename to .agents/skills/test-oracles/SKILL.md index cfa82335..4c100704 100644 --- a/docs/agents/skills/test-oracles/SKILL.md +++ b/.agents/skills/test-oracles/SKILL.md @@ -1,3 +1,8 @@ +--- +name: test-oracles +description: Property, fuzz, and security tests that accept or reject with an independent oracle. Use when adding Hypothesis tests or reviewing soft fuzz. +--- + # Skill: test-oracles Write property, fuzz, and security tests that decide accept or reject with an independent oracle. Never soft-fuzz that only checks nothing crashed. @@ -52,4 +57,4 @@ uv run pytest tests/backend/test_rrc_oracle_bugs.py tests/backend/test_rrc_proto task test:eect ``` -Also read: `docs/agents/conventions/tests.md`, `docs/agents/skills/exploratory-testing/SKILL.md`. +Also read: `.agents/conventions/tests.md`, `.agents/skills/exploratory-testing/SKILL.md`. diff --git a/docs/agents/skills/vue-mega-page-split/SKILL.md b/.agents/skills/vue-mega-page-split/SKILL.md similarity index 88% rename from docs/agents/skills/vue-mega-page-split/SKILL.md rename to .agents/skills/vue-mega-page-split/SKILL.md index 00b24653..6f52e5bd 100644 --- a/docs/agents/skills/vue-mega-page-split/SKILL.md +++ b/.agents/skills/vue-mega-page-split/SKILL.md @@ -1,3 +1,8 @@ +--- +name: vue-mega-page-split +description: Extract Vue mega-page shells into internal/sections/helpers without behaviour change. Use when splitting listed mega-pages from module-ownership.md. +--- + # Skill: vue-mega-page-split Extract or split Vue mega-page shells under `meshchatx/src/frontend/components/` @@ -5,7 +10,7 @@ without changing behaviour. ## When to use -- Splitting listed mega-pages from `docs/agents/module-ownership.md` +- Splitting listed mega-pages from `.agents/module-ownership.md` - Moving presentational panels into `internal/` or `settings/sections/` - Extracting pure helpers next to a page or under `js//` @@ -13,17 +18,17 @@ Not for greenfield pages. Use `page-toast-tests` for new routes and nav wiring. Also read: -- `docs/agents/module-ownership.md` (Frontend mega-pages) -- `docs/agents/conventions/frontend.md` -- `docs/agents/conventions/tests.md` -- `docs/agents/skills/test-loop/SKILL.md` +- `.agents/module-ownership.md` (Frontend mega-pages) +- `.agents/conventions/frontend.md` +- `.agents/conventions/tests.md` +- `.agents/skills/test-loop/SKILL.md` ## Hard rules 1. Mechanical extract only. No renames, no toast or i18n churn, no API path changes in the same change as a move. 2. One concern per change: move or behaviour, never both. 3. Match the Options API style of the parent file. Do not introduce Composition API, provide or inject, Pinia, or a composables tree in an extract. -4. Follow inventory names in `docs/agents/module-ownership.md`. Do not invent alternate folders. +4. Follow inventory names in `.agents/module-ownership.md`. Do not invent alternate folders. 5. Shell stays orchestration. Data ownership, `window.api`, map or canvas lifecycle init and teardown, and multi-child toast firing stay on the page shell unless a later behaviour change explicitly moves them. 6. One slice per PR or commit series. Prefer one panel, one settings section, or one pure helper module. 7. Promote to shared root components only when two or more unrelated features need the same UI. @@ -32,7 +37,7 @@ Also read: ## Placement -Placement table (page-private panels, settings chunks, pure logic, cross-feature primitives, nav/tools wiring): `docs/agents/module-ownership.md` (Frontend mega-pages section). Do not invent folders outside that table. +Placement table (page-private panels, settings chunks, pure logic, cross-feature primitives, nav/tools wiring): `.agents/module-ownership.md` (Frontend mega-pages section). Do not invent folders outside that table. ## Pre-extract inventory (mandatory) diff --git a/AGENTS.md b/AGENTS.md index cb33111b..2ca8fad9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,15 +1,16 @@ # MeshChatX agent entry -Start at [docs/agents/README.md](docs/agents/README.md). +Start at [.agents/README.md](.agents/README.md). -For architecture and invariants, read [docs/agents/overview.md](docs/agents/overview.md). -For mesh design, read [docs/agents/conventions/reticulum-zen.md](docs/agents/conventions/reticulum-zen.md). +Architecture and invariants: [.agents/overview.md](.agents/overview.md). +Mesh design: [.agents/conventions/reticulum-zen.md](.agents/conventions/reticulum-zen.md). +Prose: [.agents/skills/no-ai-slop/SKILL.md](.agents/skills/no-ai-slop/SKILL.md) before writing or editing docs, UI copy, or commit messages longer than a sentence. -## Linux Landlock (quick) +## Linux Landlock -MeshChatX applies an optional filesystem sandbox on Linux (`MESHCHAT_LANDLOCK`, see overview). Besides SQLite `temp_store`, it affects **subprocesses** and **user-local tools** (pipx Argos Translate, `~/.local/bin` wrappers, rnsh/rnx when launched as PATH scripts). +Optional filesystem sandbox on Linux (`MESHCHAT_LANDLOCK`, see overview). Besides SQLite `temp_store`, it affects subprocesses and user-local tools (pipx Argos Translate, `~/.local/bin` wrappers, rnsh/rnx launched as PATH scripts). - Implementation: `meshchatx/src/backend/landlock_sandbox.py` -- SQLite symptoms and pragmas: [docs/agents/skills/landlock-sqlite/SKILL.md](docs/agents/skills/landlock-sqlite/SKILL.md) +- SQLite symptoms and pragmas: [.agents/skills/landlock-sqlite/SKILL.md](.agents/skills/landlock-sqlite/SKILL.md) - Integration probes (subprocess spawn, translator Argos, home write denial): `tests/backend/test_landlock_integration_surfaces.py` and `tests/backend/landlock_integration_support.py` - After changing Landlock rules or any code that `subprocess`/`Popen`s external binaries, extend read/RW roots and add a probe test in that integration file. diff --git a/docs/agents/README.md b/docs/agents/README.md deleted file mode 100644 index aa746169..00000000 --- a/docs/agents/README.md +++ /dev/null @@ -1,95 +0,0 @@ -# Agent guidance for MeshChatX - -Neutral, tool-agnostic notes for automated agents and human contributors who work like agents. -This tree is not part of the in-app user documentation. End-user docs live under `docs/en/`. - -## Start here - -1. Read [overview.md](overview.md) for architecture, storage, security, env vars, and invariants. -2. Read [conventions/reticulum-zen.md](conventions/reticulum-zen.md) before any mesh-facing design or code. -3. Apply [conventions/](conventions/) for the surface you are editing. -4. Open a [skills/](skills/) guide when the task matches that workflow. - -Root [AGENTS.md](../../AGENTS.md) is a short pointer to this directory. - -Optional editor rules (if present under `.cursor/rules/` or similar): - -- Always on: MeshChatX core standards and Reticulum Zen gates -- Globs: backend, frontend, Android, tests - -## Layout - -| Path | Purpose | -| ------------------------------------------------------------ | ----------------------------------------- | -| [overview.md](overview.md) | Project brief and critical invariants | -| [module-ownership.md](module-ownership.md) | Domain to manager / HTTP / WS / tests map | -| [conventions/reticulum-zen.md](conventions/reticulum-zen.md) | Zen of Reticulum hard gates | -| [conventions/core.md](conventions/core.md) | Always-on standards | -| [conventions/frontend.md](conventions/frontend.md) | Vue UI | -| [conventions/backend.md](conventions/backend.md) | Python / HTTP / SQLite | -| [conventions/path-jail.md](conventions/path-jail.md) | Local FS APIs: jail, symlinks, tests | -| [conventions/android.md](conventions/android.md) | Android WebView bridge | -| [conventions/tests.md](conventions/tests.md) | Test placement, oracles, verification | - -## Skills - -### UI and wiring - -| Skill | Use when | -| ---------------------------------------------------------------------------- | ------------------------------------------------------ | -| [page-toast-tests](skills/page-toast-tests/SKILL.md) | New pages, toasts, i18n, tests | -| [contribution-registries](skills/contribution-registries/SKILL.md) | Nav, tools, commands, settings search, WS event wiring | -| [vue-mega-page-split](skills/vue-mega-page-split/SKILL.md) | Extract Vue mega-pages into internal/sections/helpers | -| [meshchat-orchestration-split](skills/meshchat-orchestration-split/SKILL.md) | Extract HTTP/WS from meshchat.py, multi-file scanners | - -### Mesh protocols (RNS / LXMF / LXST / RRC) - -| Skill | Use when | -| ---------------------------------------------------------------- | --------------------------------------------------------- | -| [reticulum-design-gates](skills/reticulum-design-gates/SKILL.md) | Any mesh design review against Zen of Reticulum | -| [rns-link-api](skills/rns-link-api/SKILL.md) | Generic RNS Link WebSocket / plugin transport | -| [lxmf-messaging](skills/lxmf-messaging/SKILL.md) | LXMF send/receive, stamps, propagation, attachments | -| [lxst-telephony](skills/lxst-telephony/SKILL.md) | LXST calls, audio WS, telephony managers | -| [rrc-relay-chat](skills/rrc-relay-chat/SKILL.md) | Relay Chat hubs, rooms, +k keys, moderation, client state | - -### Identity and data - -| Skill | Use when | -| -------------------------------------------------------------------------- | --------------------------------------------------- | -| [identity-restore](skills/identity-restore/SKILL.md) | Identity key vs database zip restore | -| [identity-switch-teardown](skills/identity-switch-teardown/SKILL.md) | Live identity switch without cross-identity leaks | -| [database-migrations-backups](skills/database-migrations-backups/SKILL.md) | Schema bumps, backups, snapshots, restore safety | -| [landlock-sqlite](skills/landlock-sqlite/SKILL.md) | Landlock + SQLite, subprocess/user-local CLI probes | - -### Security and plugins - -| Skill | Use when | -| ------------------------------------------------------------------ | ------------------------------------------- | -| [auth-csrf-ws-security](skills/auth-csrf-ws-security/SKILL.md) | CSRF, auth, WS mutator denylist | -| [path-jail-local-fs](skills/path-jail-local-fs/SKILL.md) | Local file browse/upload/delete path jails | -| [plugin-install-security](skills/plugin-install-security/SKILL.md) | Plugin install, RSG, permissions, integrity | - -### Platforms and boot - -| Skill | Use when | -| ---------------------------------------------------------------------- | --------------------------------------------- | -| [deferred-network-startup](skills/deferred-network-startup/SKILL.md) | HTTP-up vs RNS-ready, status, 503s, RNS panic | -| [electron-frozen-packaging](skills/electron-frozen-packaging/SKILL.md) | Frozen desktop spawn, loading, crash recovery | -| [android-webview-bridge](skills/android-webview-bridge/SKILL.md) | Android chooser MIME, storage, WebView nav | - -### Verification - -| Skill | Use when | -| ---------------------------------------------------------- | ---------------------------------------------------- | -| [test-loop](skills/test-loop/SKILL.md) | Focused verification without hung shells | -| [test-oracles](skills/test-oracles/SKILL.md) | Property/fuzz oracles: accept/reject, not soft fuzz | -| [exploratory-testing](skills/exploratory-testing/SKILL.md) | Adversarial exploration to find bugs with hypotheses | - -## Product docs (users) - -- `docs/en/architecture.md` -- `docs/en/identity-and-security.md` -- `docs/en/getting-started.md` -- `docs/en/rns-link-api.md` -- `docs/en/platform-guides/linux-sandbox.md` -- `CONTRIBUTING.md` diff --git a/docs/agents/conventions/core.md b/docs/agents/conventions/core.md deleted file mode 100644 index 68f8f685..00000000 --- a/docs/agents/conventions/core.md +++ /dev/null @@ -1,14 +0,0 @@ -# Core conventions - -- Read `docs/agents/overview.md` for layout, commands, and domain traps. -- Mesh-facing work: read `docs/agents/conventions/reticulum-zen.md` and run `docs/agents/skills/reticulum-design-gates/SKILL.md` gates first. -- Prefer `task` targets (`format`, `lint`, `test:quick`, `test:backend`, `test:frontend`). -- Minimal diffs. Match nearby style. Keep SPDX headers on new project files (`0BSD` unless file already differs). -- No emojis in repo text. No TODO/FIXME comment noise. -- No emdashes or semicolons in comments or docs you write. -- No backticks in code comments. Prefer plain words or quoted identifiers. -- Do not commit/push unless asked. -- User-visible UI strings: i18n keys. Action feedback: `ToastUtils`. -- Do not invent install/run flows when Taskfile already covers them. -- Do not create markdown docs unless asked (except agent guidance under `docs/agents/` when requested). -- Do not generate exploit PoCs, malware, or attack tooling. diff --git a/docs/en/architecture.md b/docs/en/architecture.md index d29fd653..d20d4aa2 100644 --- a/docs/en/architecture.md +++ b/docs/en/architecture.md @@ -10,7 +10,7 @@ MeshChatX is a fork of Reticulum MeshChat with LXST telephony, RRC relay chat, N - Keep the Python backend and Vue frontend independently testable. - Run in constrained environments with predictable SQLite behaviour. -Mesh features should follow Reticulum’s post-IP design patterns (portable identity hashes, announces, store-and-forward, transport-agnostic APIs, scarce payloads). Agent and contributor gates live in `docs/agents/conventions/reticulum-zen.md` and `docs/agents/skills/reticulum-design-gates/SKILL.md`, derived from the [Zen of Reticulum](https://reticulum.network/manual/zen.html). +Mesh features should follow Reticulum’s post-IP design patterns (portable identity hashes, announces, store-and-forward, transport-agnostic APIs, scarce payloads). Agent and contributor gates live in `.agents/conventions/reticulum-zen.md` and `.agents/skills/reticulum-design-gates/SKILL.md`, derived from the [Zen of Reticulum](https://reticulum.network/manual/zen.html). ## Process overview @@ -35,7 +35,7 @@ Optional **Electron** wraps the same backend binary and loads the UI from the lo ## Application shell -`ReticulumMeshChat` in `meshchatx/meshchat.py` is the orchestration layer. It wires HTTP via `meshchatx/src/backend/http/`, starts and stops identity contexts, wires crash recovery, and coordinates shared process concerns. Domain to route ownership is documented in `docs/agents/module-ownership.md`. +`ReticulumMeshChat` in `meshchatx/meshchat.py` is the orchestration layer. It wires HTTP via `meshchatx/src/backend/http/`, starts and stops identity contexts, wires crash recovery, and coordinates shared process concerns. Domain to route ownership is documented in `.agents/module-ownership.md`. Path helpers live in `meshchatx/src/path_utils.py`, `ssl_self_signed.py`, and `env_utils.py`. `meshchat.py` re-exports them for compatibility. diff --git a/meshchatx.rsm b/meshchatx.rsm index 43e66ace..6365397b 100644 Binary files a/meshchatx.rsm and b/meshchatx.rsm differ