@lazyingart/agintiflow 0.20.47 → 0.20.49

package/references/skill-mesh-sharing-design.md

@@ -0,0 +1,1123 @@
+# AgInTiFlow Skill Mesh Sharing Design
+
+## Goal
+
+AgInTiFlow should let different users benefit from skills, tool patterns, command policies, profiles, and troubleshooting lessons learned by other users without uploading private transcripts, source code, file paths, secrets, or artifacts.
+
+The proposed feature name is **Skill Mesh**.
+
+Implementation note as of v0.20.48:
+
+- `aginti skillmesh` and `/skillmesh` exist as the first conservative MVP.
+- The shipped implementation uses signed JSON skill packs first, not tarballs, to avoid archive traversal and executable-file risk.
+- Relay nodes can run without model/API keys via `aginti skillmesh serve`.
+- Relay nodes can persist after reboot with `aginti skillmesh service install`; system services require sudo, while user services need systemd lingering for boot persistence.
+- Community imports install disabled by default and cannot override built-in skills.
+- Sync is explicit and metadata-first; no continuous background polling is enabled yet.
+
+User-facing command:
+
+```text
+/skillmesh
+```
+
+CLI command:
+
+```bash
+aginti skillmesh
+```
+
+Useful aliases can be added later:
+
+```text
+/skill-sync
+/skill-share
+aginti skillsync
+```
+
+Product default should be **Record + Share Reviewed Skills**. This sounds active, but the implementation must still be conservative: it records locally by default, shares only reviewed/high-value skill packs, syncs slowly during idle time, and never uploads raw logs or raw sessions.
+
+The sync philosophy should be **slow, strict, and high-signal**. Skill Mesh is not chat, telemetry streaming, or a real-time swarm bus. It should exchange only reviewed, deduplicated, high-value capability packs during idle time.
+
+## Core Modes
+
+The selector for `/skillmesh` should have three modes:
+
+1. **Disabled**
+
+   No housekeeping export, no community sync, no skill suggestions from shared feeds. Raw local session history still stays in `~/.agintiflow/sessions/` if normal sessions are enabled, but no Skill Mesh aggregation is used.
+
+2. **Record Locally**
+
+   AgInTiFlow records sanitized local capability metadata into `~/.agintiflow/housekeeping/`. This includes model/tool names, selected skill ids, command categories, outcome hashes, and short redacted previews. It does not upload anything.
+
+3. **Record + Share Reviewed Packs**
+
+   AgInTiFlow records locally and allows the user to review/export/share **skill packs**. Sharing must never mean uploading raw sessions automatically. It should mean publishing a small reviewed package containing reusable Markdown skills, task profile hints, safe command policy patterns, test snippets, and metadata. This should be the default mode for the product, with strict text in settings explaining what is and is not shared.
+
+Better label in UI:
+
+```text
+Record + Share Reviewed Skills
+```
+
+Settings page explanatory text:
+
+```text
+Skill sharing improves AgInTiFlow's skill set across users. Sharing is strict: AgInTiFlow never uploads raw chats, raw session logs, project source files, .env files, keys, browser storage, or artifacts by default. Only reviewed, redacted, high-value skill packs can be shared, and shared skills are deduplicated and verified before they can enter the mesh.
+```
+
+When the user selects **Disabled**, show:
+
+```text
+Skill Mesh is disabled. AgInTiFlow will not record local skill-learning metadata and will not share or receive reviewed skill packs. Enabling Record + Share Reviewed Skills can improve the shared skill set, but sharing remains strict and never uploads raw sessions or secrets.
+```
+
+Avoid label:
+
+```text
+Auto-share logs
+```
+
+because that is the wrong privacy model.
+
+## How Users Communicate Without Sharing Raw Sessions
+
+Users communicate through **capability artifacts**, not through transcripts.
+
+Shared artifact types:
+
+- `SKILL.md` files with frontmatter and workflow guidance.
+- Task profile patches or suggestions.
+- Command-policy examples, such as safe git pull/merge/rebase patterns.
+- Tool recipes, such as Android emulator screenshot capture or LaTeX compile fallback.
+- Smoke tests that prove a skill/tool pattern works.
+- Failure postmortems rewritten as generic lessons.
+- Model routing hints, such as which model is reliable for which class of task.
+
+Never share by default:
+
+- Raw prompts.
+- Raw model responses.
+- Raw `events.jsonl`.
+- Source files from the user project.
+- Absolute paths.
+- Shell output containing environment variables.
+- Screenshots/images/PDFs unless the user explicitly includes them in a reviewed example.
+- Provider keys, npm tokens, SSH data, cookies, auth headers, or `.env` content.
+
+## Local Pipeline
+
+The local machine should have a lightweight housekeeping pipeline:
+
+```text
+session events
+  -> redaction and path masking
+  -> local housekeeping ledger
+  -> candidate capability extractor
+  -> user review queue
+  -> signed skill pack
+  -> optional share/sync
+```
+
+Existing foundation:
+
+```text
+~/.agintiflow/housekeeping/events.jsonl
+~/.agintiflow/housekeeping/capabilities.json
+```
+
+Future local folders:
+
+```text
+~/.agintiflow/skillmesh/
+  config.json
+  identity.json
+  inbox/
+  outbox/
+  reviewed/
+  rejected/
+  feeds/
+  trusted-keys/
+```
+
+Candidate skill packs should stay local until reviewed.
+
+## Slow Sync And Value Gate
+
+Skill Mesh should avoid heavy or frequent communication.
+
+Default sync behavior:
+
+- No sync while an agent run is active.
+- No sync while shell tools, browser tools, package installs, tests, or model calls are running.
+- Sync only during idle windows.
+- Add jitter so many clients do not sync at the same second.
+- Cap outbound submissions per day.
+- Cap inbound downloads per sync.
+- Prefer metadata sync first, pack download second.
+- Never use Skill Mesh as a live coordination channel for active agent tasks.
+
+Suggested defaults:
+
+```json
+{
+  "syncPolicy": {
+    "enabled": false,
+    "idleOnly": true,
+    "minIdleSeconds": 90,
+    "minIntervalMinutes": 360,
+    "jitterMinutes": 30,
+    "maxOutboundPacksPerDay": 3,
+    "maxInboundPacksPerSync": 20,
+    "metadataFirst": true,
+    "downloadRequiresUserReview": true
+  }
+}
+```
+
+The local scheduler should be simple:
+
+```text
+if skillmesh.mode != "share": skip
+if agent is running: skip
+if last sync too recent: skip
+if no reviewed outbox packs and no feed refresh due: skip
+fetch feed metadata
+dedupe against local database
+download only selected/high-trust candidates
+upload only reviewed outbound packs
+```
+
+### Value Scoring
+
+The candidate extractor should not share every local observation. It should rank candidates and export only the most useful.
+
+Signals that increase value:
+
+- The same failure happened more than once and a reusable fix was found.
+- A new skill/tool recipe was used successfully with verification.
+- A command policy pattern prevented a dangerous or stuck command.
+- A generated smoke test caught a real regression.
+- A workflow applies across many projects, not only one user folder.
+- The candidate contains acceptance criteria and verification commands.
+- The candidate is small and self-contained.
+
+Signals that reduce value:
+
+- It mentions private project names, file paths, users, servers, or proprietary APIs.
+- It depends on a very specific local machine layout.
+- It duplicates an existing core skill.
+- It only says generic advice.
+- It was not verified by a test, command, screenshot, or file evidence.
+- It requires secrets, sudo passwords, or private accounts.
+
+Example scoring:
+
+```json
+{
+  "minShareScore": 80,
+  "weights": {
+    "verified": 30,
+    "reusedAcrossSessions": 20,
+    "hasSmokeTest": 20,
+    "hasClearTrigger": 10,
+    "smallAndGeneric": 10,
+    "duplicatesExistingSkill": -40,
+    "containsPrivateContext": -100
+  }
+}
+```
+
+Only reviewed packs above the threshold should enter the share outbox.
+
+## Deduplication Database
+
+Both clients and relay servers need a database to avoid duplication and noisy sync.
+
+Local database:
+
+```text
+~/.agintiflow/skillmesh/index.sqlite
+```
+
+Relay database:
+
+```text
+~/.aginti-skill-relay/index.sqlite
+```
+
+Core tables:
+
+```sql
+CREATE TABLE packs (
+  pack_hash TEXT PRIMARY KEY,
+  canonical_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  version TEXT NOT NULL,
+  author_key_id TEXT NOT NULL,
+  status TEXT NOT NULL,
+  trust_level TEXT NOT NULL,
+  value_score INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  received_at TEXT NOT NULL,
+  last_seen_at TEXT NOT NULL,
+  metadata_json TEXT NOT NULL
+);
+
+CREATE TABLE pack_signatures (
+  pack_hash TEXT NOT NULL,
+  key_id TEXT NOT NULL,
+  signature TEXT NOT NULL,
+  verified INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (pack_hash, key_id)
+);
+
+CREATE TABLE installed_packs (
+  pack_hash TEXT PRIMARY KEY,
+  enabled INTEGER NOT NULL DEFAULT 0,
+  installed_at TEXT NOT NULL,
+  source_feed TEXT NOT NULL DEFAULT ''
+);
+
+CREATE TABLE rejected_packs (
+  pack_hash TEXT PRIMARY KEY,
+  reason TEXT NOT NULL,
+  rejected_at TEXT NOT NULL
+);
+```
+
+Hash strategy:
+
+- `pack_hash`: SHA-256 of the canonical tarball bytes.
+- `canonical_id`: stable hash of normalized semantic content, excluding timestamps and signatures.
+- `skill_hash`: SHA-256 of normalized `SKILL.md` body and frontmatter.
+- `policy_hash`: SHA-256 of normalized command-policy JSON.
+
+Deduplication should use both exact and semantic hashes:
+
+- If `pack_hash` exists, skip.
+- If `canonical_id` exists with the same or higher version, skip.
+- If a skill body hash matches a core skill, mark as duplicate.
+- If a pack is rejected locally, do not re-download it unless the hash changes.
+
+Relay response should support metadata-only dedupe:
+
+```json
+{
+  "feedVersion": 1,
+  "packs": [
+    {
+      "packHash": "sha256:...",
+      "canonicalId": "skill:android-emulator-screenshot:...",
+      "name": "android-emulator-screenshot",
+      "version": "0.1.0",
+      "valueScore": 92,
+      "trustLevel": "community-reviewed",
+      "downloadUrl": "/packs/sha256-....tgz",
+      "metadataUrl": "/packs/sha256-.../metadata.json"
+    }
+  ]
+}
+```
+
+Clients should send only hashes when asking what is new:
+
+```http
+POST /sync/metadata
+```
+
+```json
+{
+  "clientProtocol": 1,
+  "knownPackHashes": ["sha256:..."],
+  "knownCanonicalIds": ["skill:..."],
+  "acceptedTrustLevels": ["core", "trusted-publisher", "community-reviewed"]
+}
+```
+
+This keeps routine communication small.
+
+## Skill Pack Format
+
+A shared skill pack should be a normal directory or tarball:
+
+```text
+skillpack.json
+skills/<skill-id>/SKILL.md
+profiles/<profile-id>.json
+policies/<policy-id>.json
+tests/<test-id>.js
+examples/<example-id>/README.md
+```
+
+`skillpack.json` should include:
+
+```json
+{
+  "schema": 1,
+  "name": "android-emulator-screenshot",
+  "version": "0.1.0",
+  "author": "local-user-or-org",
+  "license": "Apache-2.0",
+  "createdAt": "2026-05-04T00:00:00.000Z",
+  "source": "reviewed-local-learning",
+  "privacy": {
+    "rawSessionsIncluded": false,
+    "secretsRedacted": true,
+    "pathsMasked": true,
+    "requiresHumanReview": true
+  },
+  "contents": {
+    "skills": ["android-emulator-screenshot"],
+    "profiles": ["android"],
+    "tests": ["android-screenshot-smoke"]
+  },
+  "signature": {
+    "algorithm": "ed25519",
+    "publicKeyId": "..."
+  }
+}
+```
+
+The pack should be installable locally:
+
+```bash
+aginti skillmesh import ./android-emulator-screenshot.skillpack.tgz
+```
+
+and exportable:
+
+```bash
+aginti skillmesh export android-emulator-screenshot
+```
+
+## Trust Model
+
+Skill Mesh should treat shared capabilities like dependencies.
+
+Trust levels:
+
+- **Core**: shipped by the npm package.
+- **Trusted publisher**: signed by LazyingArt or a configured team key.
+- **Community reviewed**: available from a feed, but not automatically active.
+- **Local experimental**: created on this machine.
+- **Blocked**: rejected by the user or a policy rule.
+
+Installing a skill pack should show:
+
+- Author.
+- Signature status.
+- Files included.
+- Tools/commands it recommends.
+- Whether it changes command policy.
+- Whether it adds tests.
+- Whether it has examples.
+
+Default import behavior:
+
+```text
+download -> verify -> preview -> install disabled -> user enables
+```
+
+Do not auto-enable community skills that can cause shell, git, network, browser, or file-writing behavior.
+
+## Server And P2P Options
+
+There are three viable distribution modes.
+
+### 1. No Server: npm-Only Sharing
+
+This is the safest and simplest.
+
+Flow:
+
+```text
+users learn locally -> useful lessons become PRs or releases -> npm package ships updated skills
+```
+
+Pros:
+
+- Strong review.
+- Easy install and update.
+- No user data service.
+- Good for stable core skills.
+
+Cons:
+
+- Slower feedback loop.
+- Less community experimentation.
+
+### 2. Skill Relay Server
+
+Use an ECS machine as a lightweight relay/index. Suggested product name:
+
+```text
+AgInTi Skill Relay
+```
+
+The relay should store only reviewed skill packs and feed metadata.
+
+Server responsibilities:
+
+- Receive signed skill packs.
+- Reject raw session uploads.
+- Run redaction/sanity checks.
+- Compute hashes and deduplicate.
+- Expose feed indexes.
+- Serve downloads.
+- Keep reputation/signature metadata.
+- Optionally maintain review status.
+- Rate-limit clients and publishers.
+- Maintain dedupe indexes by exact and semantic hash.
+- Support metadata-only sync.
+- Quarantine untrusted uploads before feed publication.
+
+Server should not:
+
+- Store raw `~/.agintiflow/sessions`.
+- Store raw project source.
+- Store provider keys.
+- Execute uploaded code.
+- Auto-push updates to clients.
+- Accept anonymous bulk uploads without rate limits.
+- Act as a general file-sharing server.
+- Serve packs that failed redaction or archive policy checks.
+
+Possible server command:
+
+```bash
+aginti-skill-relay serve --host 0.0.0.0 --port 7377 --data ~/.aginti-skill-relay
+```
+
+Client sync:
+
+```bash
+aginti skillmesh feed add lazyingart https://skills.flow.lazying.art/feed.json
+aginti skillmesh sync
+aginti skillmesh inbox
+```
+
+### Strict Server Contract
+
+The relay should be defensive by default.
+
+Inbound upload checks:
+
+- Require authenticated publisher identity or a temporary upload token.
+- Require signed `skillpack.json`.
+- Require archive size under a small limit, for example 2 MB initially.
+- Require max file count, for example 100 files.
+- Require all paths to be relative and normalized.
+- Reject symlinks, hardlinks, device files, absolute paths, and `..` path traversal.
+- Reject executable binaries by default.
+- Reject nested archives by default.
+- Reject any archive containing raw session filenames.
+- Scan every text file for token/secret patterns.
+- Require `privacy.rawSessionsIncluded=false`.
+- Require `privacy.requiresHumanReview=true` unless the publisher is trusted.
+- Put uploads into `pending` before public feed inclusion.
+
+Outbound feed checks:
+
+- Serve only approved or trusted packs.
+- Include content hashes and signature metadata.
+- Include trust level and review status.
+- Do not expose uploader IPs or private client metadata.
+- Keep feed response small and cacheable.
+- Use ETag/If-None-Match for low traffic.
+
+Abuse controls:
+
+- Per-IP rate limits.
+- Per-publisher daily upload limits.
+- Maximum pending queue size.
+- Manual blocklist for bad keys, bad IPs, and bad pack hashes.
+- Audit log of decisions without storing raw private content.
+
+The relay should fail closed: if validation cannot prove a pack is safe, the pack stays private/pending.
+
+### Strict Client Contract
+
+Clients must also be defensive.
+
+Before upload:
+
+- Export only reviewed packs from `~/.agintiflow/skillmesh/reviewed/`.
+- Run local redaction scan.
+- Run archive policy scan.
+- Show a human-readable manifest preview.
+- Require explicit confirmation unless the publisher key is configured for unattended sharing.
+- Upload only pack metadata first if possible.
+
+Before download/install:
+
+- Fetch metadata first.
+- Deduplicate locally.
+- Verify signature when present.
+- Reject packs with unsupported schema.
+- Reject packs requiring disabled capabilities.
+- Install community packs disabled by default.
+- Show diff/manifest before enabling.
+- Never let a downloaded pack directly change provider keys, `.env`, shell policy, or auto-update settings.
+
+Client setting:
+
+```json
+{
+  "downloadPolicy": {
+    "autoDownloadMetadata": true,
+    "autoDownloadPacks": false,
+    "autoEnableSkills": false,
+    "allowPolicyChanges": false,
+    "allowExecutableTests": false
+  }
+}
+```
+
+### 3. P2P Mesh
+
+True P2P can come later. It is harder because NAT traversal, identity, signatures, spam, and moderation become product concerns.
+
+Pragmatic first step:
+
+- Use the ECS server as a rendezvous and relay.
+- Keep client identity keypairs local.
+- Sign every skill pack.
+- Let users subscribe to feeds rather than broadcast everything.
+
+This gives most of the value of P2P without building a fragile distributed network first.
+
+### Volunteer Shared Nodes
+
+A volunteer shared node is a user-run relay that can exchange reviewed skill packs with the major node and with trusted peers.
+
+Modes:
+
+- **Client only**: syncs with feeds, does not accept inbound connections.
+- **Volunteer node**: serves a local feed and accepts reviewed pack submissions from configured peers.
+- **Major node**: public, stable relay operated by LazyingArt or a trusted maintainer.
+
+Volunteer nodes should be opt-in and conservative:
+
+```bash
+aginti skillmesh node init
+aginti skillmesh node check-public
+aginti skillmesh node serve --port 7377
+```
+
+Node health checks:
+
+- Public URL configured.
+- TLS available or explicitly disabled for LAN-only.
+- `/health` reachable from outside if public.
+- Feed endpoint reachable.
+- Upload endpoint protected.
+- Data directory not inside a project repo.
+- Rate limits enabled.
+- Pack quarantine enabled.
+
+If a machine is behind LAN/NAT, the user can provide an external tunnel:
+
+```bash
+ngrok http 7377
+aginti skillmesh node set-url https://example.ngrok-free.app
+aginti skillmesh node check-public
+```
+
+The node should not guess that it is public. It should verify from an external check endpoint or ask the major relay to call back:
+
+```text
+local node -> major node: please verify https://example.ngrok-free.app/health with nonce abc
+major node -> local node: GET /health?nonce=abc
+local node -> major node: verification succeeds
+```
+
+Only verified nodes should be listed as reachable peers.
+
+### Verified Node Admission
+
+A node can join the mesh only after a currently verified node can connect to it and complete the designed verification API.
+
+Default admission authority:
+
+```text
+skills.flow.lazying.art
+```
+
+This means a LAN machine exposed by ngrok or a public `ip:port` is not trusted just because the user typed a URL. The major node must verify it first.
+
+Admission flow:
+
+```text
+candidate node starts local relay
+candidate node sets public URL, for example ngrok URL or https://ip:port
+candidate node asks major node to verify
+major node creates nonce and expected callback challenge
+major node calls candidate /health and /node/verify endpoints
+candidate proves it owns the local node identity key
+major node checks protocol version, TLS/public URL, feed endpoint, upload protection, rate limits, and quarantine
+major node adds candidate to node list as verified
+verified node appears in feed metadata for optional peer sync
+```
+
+Verification API shape:
+
+```http
+POST /nodes/register
+GET  /health?nonce=<nonce>
+POST /node/verify
+GET  /feed.json
+```
+
+Candidate registration payload:
+
+```json
+{
+  "nodeId": "ed25519:key-id",
+  "publicUrl": "https://example.ngrok-free.app",
+  "role": "volunteer",
+  "protocol": 1,
+  "capabilities": ["feed", "metadata-sync"],
+  "signature": "signature over publicUrl + nonce"
+}
+```
+
+Major node checks:
+
+- Public URL is reachable from the major node.
+- Node identity signature verifies.
+- `/health` returns the expected nonce.
+- `/feed.json` is valid and small.
+- Upload endpoint is either disabled or protected.
+- Node advertises idle/slow sync policy.
+- Node does not claim to accept raw sessions.
+- Node version/protocol is compatible.
+
+Node list table:
+
+```sql
+CREATE TABLE verified_nodes (
+  node_id TEXT PRIMARY KEY,
+  public_url TEXT NOT NULL,
+  role TEXT NOT NULL,
+  protocol INTEGER NOT NULL,
+  status TEXT NOT NULL,
+  first_verified_at TEXT NOT NULL,
+  last_verified_at TEXT NOT NULL,
+  last_seen_at TEXT NOT NULL,
+  failure_count INTEGER NOT NULL DEFAULT 0,
+  metadata_json TEXT NOT NULL
+);
+```
+
+Removal policy:
+
+- Recheck verified nodes occasionally, for example every 6-24 hours.
+- If a node fails once, mark `degraded`.
+- If it fails repeatedly, mark `offline`.
+- If it stays offline beyond a threshold, remove it from the public node list.
+- Keep the historical record locally for audit, but do not advertise unavailable nodes.
+
+Suggested thresholds:
+
+```json
+{
+  "nodeVerification": {
+    "recheckIntervalHours": 12,
+    "degradedAfterFailures": 1,
+    "offlineAfterFailures": 3,
+    "removeAfterOfflineDays": 7
+  }
+}
+```
+
+## ECS Deployment Role
+
+The Alibaba Cloud ECS host can run a Skill Relay node.
+
+Recommended architecture:
+
+```text
+nginx or caddy
+  -> aginti-skill-relay node process
+  -> ~/.aginti-skill-relay/index.sqlite
+  -> ~/.aginti-skill-relay/packs/
+```
+
+Minimum endpoints:
+
+```text
+GET  /health
+GET  /feed.json
+GET  /packs/<hash>.tgz
+POST /submit
+GET  /packs/<hash>/metadata.json
+```
+
+Major node role:
+
+- Stable public rendezvous point.
+- Canonical community feed.
+- Deduplication authority for public packs.
+- Optional verification callback service for volunteer nodes.
+- Optional relay for metadata exchange between trusted nodes.
+- Not a raw memory server.
+
+Recommended domain:
+
+```text
+skills.flow.lazying.art
+```
+
+Possible deployment command on `sshem`:
+
+```bash
+npm install -g @lazyingart/agintiflow
+aginti skillmesh serve \
+  --role major \
+  --host 127.0.0.1 \
+  --port 7377 \
+  --data ~/.aginti-skill-relay \
+  --public-url https://skills.flow.lazying.art
+```
+
+With nginx/caddy terminating TLS:
+
+```text
+https://skills.flow.lazying.art
+  -> 127.0.0.1:7377
+```
+
+Initial server config:
+
+```json
+{
+  "role": "major",
+  "publicUrl": "https://skills.flow.lazying.art",
+  "dataDir": "~/.aginti-skill-relay",
+  "acceptUploads": true,
+  "requireSignatures": true,
+  "requireReview": true,
+  "maxPackBytes": 2097152,
+  "maxFilesPerPack": 100,
+  "rateLimits": {
+    "submitPerIpPerHour": 10,
+    "submitPerPublisherPerDay": 20,
+    "metadataPerIpPerMinute": 60
+  }
+}
+```
+
+### Major Node Bootstrap On `sshem`
+
+The `sshem` ECS machine should be treated as the first **major node**. Other users who enable `Record + Share Reviewed Skills` can sync with it, but the node should still accept only reviewed/signed packs and should publish feeds slowly.
+
+Host assumptions from the current ECS login:
+
+```text
+OS: Ubuntu 24.04 LTS
+role: public major relay
+service user: aginti-relay
+data: /var/lib/aginti-skill-relay
+logs: /var/log/aginti-skill-relay
+public domain: skills.flow.lazying.art
+internal port: 7377
+```
+
+Bootstrap outline:
+
+```bash
+sudo adduser --system --group --home /var/lib/aginti-skill-relay aginti-relay
+sudo mkdir -p /var/lib/aginti-skill-relay /var/log/aginti-skill-relay
+sudo chown -R aginti-relay:aginti-relay /var/lib/aginti-skill-relay /var/log/aginti-skill-relay
+npm install -g @lazyingart/agintiflow
+```
+
+Service command:
+
+```bash
+sudo -u aginti-relay aginti skillmesh serve \
+  --role major \
+  --host 127.0.0.1 \
+  --port 7377 \
+  --data /var/lib/aginti-skill-relay \
+  --public-url https://skills.flow.lazying.art
+```
+
+Systemd shape:
+
+```ini
+[Unit]
+Description=AgInTi Skill Relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=aginti-relay
+Group=aginti-relay
+WorkingDirectory=/var/lib/aginti-skill-relay
+Environment=NODE_ENV=production
+ExecStart=/usr/bin/env aginti skillmesh serve --role major --host 127.0.0.1 --port 7377 --data /var/lib/aginti-skill-relay --public-url https://skills.flow.lazying.art
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/aginti-skill-relay /var/log/aginti-skill-relay
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Nginx/Caddy should terminate TLS and proxy only the relay domain to `127.0.0.1:7377`. The relay process itself should not bind directly to `0.0.0.0` on the major node unless there is no reverse proxy.
+
+Firewall:
+
+```text
+allow 22/tcp for SSH
+allow 80/tcp for ACME HTTP challenge if needed
+allow 443/tcp for HTTPS
+deny public 7377/tcp
+```
+
+Backups:
+
+- Back up `index.sqlite`, `packs/`, `trusted-keys/`, and `review-state/`.
+- Do not back up temporary upload quarantine forever; expire rejected uploads.
+- Keep audit logs but rotate them.
+- Never back up or store submitted raw sessions because those should be rejected before persistence.
+
+Major node publishing cadence:
+
+```text
+incoming upload -> quarantine -> validation -> pending review -> approved feed batch
+feed batch interval: 30-60 minutes
+metadata cache: ETag + max-age
+pack files: immutable by hash
+```
+
+Major node failure mode:
+
+- If validation worker fails, uploads stay pending.
+- If database write fails, upload fails.
+- If redaction scanner fails, upload is rejected or held pending.
+- If feed generation fails, keep serving the last known good feed.
+- If disk usage is high, stop accepting uploads before serving breaks.
+
+Submission policy:
+
+- Require signed packs.
+- Require `privacy.rawSessionsIncluded=false`.
+- Reject archives containing `.env`, `.git`, `.aginti-sessions`, `.sessions`, `events.jsonl`, `state.json`, `storage-state.json`, or obvious private paths.
+- Run content scans for token patterns.
+- Put new packs into `pending` until approved or trusted.
+- Reject too frequent submissions.
+- Reject duplicate exact hashes immediately.
+- Merge duplicate semantic packs into the same canonical record.
+
+## Sync Frequency Policy
+
+Skill Mesh should be closer to package update checks than chat messages.
+
+Default sync cadence:
+
+```text
+metadata refresh: every 6-12 hours
+pack upload: idle-only, max 3/day by default
+pack download: manual review or trusted feed only
+major relay feed publish: batch every 30-60 minutes
+volunteer node peer sync: every 12-24 hours
+```
+
+Reasons:
+
+- Skills are slow-changing knowledge.
+- Frequent sync increases privacy and abuse risk.
+- Low-frequency sync makes server costs predictable.
+- Idle-only sync avoids interfering with agent work.
+- Batch publishing gives time for validation and review.
+
+The UI should show sync state:
+
+```text
+Skill Mesh: Record + Share Reviewed Skills
+last sync: 2026-05-04 13:06
+next sync: after 18:58, idle-only
+outbox: 1 reviewed pack pending
+inbox: 4 new candidates, 0 enabled
+relay: skills.flow.lazying.art healthy
+```
+
+## Commands
+
+Interactive:
+
+```text
+/skillmesh
+```
+
+Selector:
+
+```text
+Skill Mesh
+> Record + Share Reviewed Skills
+  Record Locally
+  Disabled
+```
+
+CLI:
+
+```bash
+aginti skillmesh status
+aginti skillmesh off
+aginti skillmesh record
+aginti skillmesh share
+aginti skillmesh review
+aginti skillmesh export <name>
+aginti skillmesh import <file-or-url>
+aginti skillmesh feed add <name> <url>
+aginti skillmesh sync
+aginti skillmesh serve
+aginti skillmesh node init
+aginti skillmesh node check-public
+aginti skillmesh node set-url <url>
+```
+
+Config:
+
+```json
+{
+  "mode": "share",
+  "feeds": [],
+  "shareRequiresReview": true,
+  "autoInstallSharedSkills": false,
+  "trustedPublishers": [],
+  "syncPolicy": {
+    "idleOnly": true,
+    "minIntervalMinutes": 360,
+    "maxOutboundPacksPerDay": 3
+  }
+}
+```
+
+Environment override:
+
+```bash
+AGINTIFLOW_SKILLMESH=off
+AGINTIFLOW_SKILLMESH=record
+AGINTIFLOW_SKILLMESH=share
+```
+
+## Safety Rules
+
+Hard rules:
+
+- Never upload raw session directories.
+- Never upload `.aginti-sessions/` or `.sessions/`.
+- Never upload `.env`, `.npmrc`, SSH keys, browser storage, cookies, or auth tokens.
+- Never enable shared skills automatically if they affect shell, git, network, filesystem writes, browser auth, or package installation.
+- Keep the sharing state visible through `aginti skillmesh status`.
+
+Good defaults:
+
+- `Record + Share Reviewed Skills` for product default, because it can improve the shared skill set while still requiring strict reviewed-pack sharing.
+- `Record Locally` for users who want learning logs but no network sharing.
+- Shared packs install disabled until enabled.
+- ECS relay accepts uploads only after local pack validation.
+- Sync is idle-only and low-frequency.
+- Metadata sync happens before pack transfer.
+- Deduplication happens before download or upload.
+
+## Implementation Stages
+
+### Stage 1: Local Skill Mesh
+
+- Add `/skillmesh` selector with three modes.
+- Store config in `~/.agintiflow/skillmesh/config.json`.
+- Add `aginti skillmesh status`.
+- Keep using the existing housekeeping ledger.
+- Add local review queue from housekeeping candidates.
+
+### Stage 2: Skill Pack Export/Import
+
+- Add `aginti skillmesh export`.
+- Add `aginti skillmesh import`.
+- Support signature generation and verification.
+- Install imported skills disabled by default.
+
+### Stage 3: Relay Server
+
+- Add a separate npm binary:
+
+```bash
+npm install -g @lazyingart/aginti-skill-relay
+aginti-skill-relay serve
+```
+
+or keep it inside AgInTiFlow:
+
+```bash
+aginti skillmesh serve
+```
+
+Recommendation: start inside AgInTiFlow for speed, split into `@lazyingart/aginti-skill-relay` once the protocol stabilizes.
+
+Stage 3 should include:
+
+- SQLite dedupe database.
+- Pack archive validator.
+- Secret scanner.
+- Signature verifier.
+- Pending/reviewed/rejected states.
+- Metadata-only sync endpoint.
+- Public reachability check for volunteer nodes.
+- Nginx/Caddy deployment docs for ECS.
+
+### Stage 4: Community Feed And Review
+
+- Add feed subscription.
+- Add pending inbox.
+- Add publisher trust list.
+- Add simple moderation state on the relay.
+- Publish stable reviewed skills through npm releases.
+
+### Stage 5: Volunteer Node Federation
+
+- Add volunteer node mode.
+- Add ngrok/public URL configuration.
+- Add major-node callback verification.
+- Add peer allowlists.
+- Add low-frequency node-to-node metadata sync.
+- Keep major node as the default rendezvous and dedupe authority.
+- Remove nodes from the advertised node list when repeated reachability checks fail.
+
+## Naming Recommendation
+
+Use:
+
+```text
+Skill Mesh
+/skillmesh
+aginti skillmesh
+AgInTi Skill Relay
+```
+
+Why:
+
+- `Skill Mesh` describes distributed capability sharing without promising raw P2P networking immediately.
+- `Skill Relay` is honest for the ECS role: it relays and indexes reviewed packs.
+- The names are short enough for CLI and clear enough for docs.
+
+Avoid:
+
+```text
+Skill Cloud
+Skill Brain
+Auto Learn Share
+Swarm Memory
+```
+
+because they imply centralized memory, automatic uploads, or raw agent transcript sharing.