diff --git a/omp-docs/.okf/config.yaml b/omp-docs/.okf/config.yaml new file mode 100644 index 0000000..3b6a360 --- /dev/null +++ b/omp-docs/.okf/config.yaml @@ -0,0 +1,107 @@ +# OKF Bundle Configuration +# This file configures tooling behavior for the pi Agent Documentation Bundle. +# It is not part of the OKF v0.1 spec — it is an extension for automation. + +bundle: + name: "pi Agent Documentation Bundle" + version: "0.1" + author: "pi agent system" + description: "Cached documentation for tools, configurations, and systems used during pi agent sessions." + root: "/home/dank/.pi/agent/docs" + +generator: + # Index generation settings + index: + auto_generate: true # Regenerate index.md when files change + exclude: # Filenames to never include in auto-generated indexes + - log.md + - config.yaml + description_format: "{title} — {description}" # Format for index entries + sort: alphabetical # Sort order: alphabetical | size | modified + max_depth: 1 # Only list immediate children (not recursive) + + # Frontmatter template for new files + frontmatter_template: | + --- + type: {type} + title: {title} + description: {description} + tags: [] + timestamp: {timestamp} + --- + +validator: + # Validation rules — which checks to run + checks: + - name: "missing_type" + severity: "error" + description: "Every concept must have a `type` field in frontmatter" + run: "grep -L '^type:' {file}" + + - name: "missing_description" + severity: "warning" + description: "Every concept should have a `description` field" + run: "grep -L '^description:' {file}" + + - name: "missing_timestamp" + severity: "info" + description: "Consider adding a `timestamp` for staleness detection" + run: "grep -L '^timestamp:' {file}" + + - name: "oversized_file" + severity: "warning" + description: "Files over 500 lines should be split into separate concepts" + threshold: 500 # lines + run: "wc -l {file} | awk '$1 > 500'" + + - name: "empty_frontmatter" + severity: "error" + description: "Frontmatter block exists but contains no parseable YAML" + run: "head -n 4 {file} | grep -c '^---'" + + - name: "index_mismatch" + severity: "warning" + description: "index.md does not list all non-reserved .md files in directory" + run: "compare-index {directory}" + + # Staleness detection + staleness: + warning_days: 90 # Flag files older than 90 days + error_days: 180 # Flag files older than 180 days as stale + timestamp_field: "timestamp" + + # Cross-link validation + linking: + check_absolute_links: true # Validate absolute (bundle-relative) links resolve + check_relative_links: true # Validate relative links resolve + tolerate_broken: true # OKF spec says consumers must tolerate broken links, + # but this validator can flag them for cleanup + +fields: + # Custom field definitions beyond the OKF v0.1 spec + required: + - type # Non-negotiable — defines concept kind + + recommended: + - title # Human-readable display name + - description # One-line summary for previews and index listings + - timestamp # Last meaningful change for staleness detection + - tags # Cross-cutting categorization + + optional: + - resource # URI identifying the underlying asset + - status # Draft | Current | Deprecated | Archived + - version # Version string for versioned concepts + - see_also # Explicit list of related concept paths + - related_concepts # Tags or paths to related concepts + + # Predefined type values recognized by this bundle + types: + - concept # A single concept or idea + - reference # Reference material, specifications, tables + - guide # How-to, walkthrough, procedural + - configuration # Config file reference or setup instructions + - changelog # Update history + - specification # Formal spec or standard + - tutorial # Step-by-step learning content + - tool # Tool documentation, setup, and usage diff --git a/omp-docs/agentic-web-research/agentic-search-best-practices.md b/omp-docs/agentic-web-research/agentic-search-best-practices.md new file mode 100644 index 0000000..ec33822 --- /dev/null +++ b/omp-docs/agentic-web-research/agentic-search-best-practices.md @@ -0,0 +1,121 @@ +--- +type: concept +title: Agentic Search Best Practices +description: Query formulation, extraction, validation, retry, and rate limiting for an agent that searches the web. +tags: + - agentic + - search + - rag + - retrieval + - unverified +verified: 2026-08-28 +timestamp: 2026-08-11 +--- + +# Agentic Search Best Practices + +An agent that searches well does not fire one query and trust one answer. It rewrites queries, reads the strongest sources, and checks its own work. + +This page gives the practices. See [Research Effectiveness](research-effectiveness.md) for how to orchestrate the loop. + +## The Search Pipeline + +```mermaid +graph LR + A[User question] --> B[Query rewriter] + B --> C[Query 1] + B --> C2[Query 2] + B --> C3[Query 3] + C --> D[SearXNG] + C2 --> D + C3 --> D + D --> E[Extract content] + E --> F[Re-rank + dedupe] + F --> G[Validate facts] + G --> H[Synthesize + cite] +``` + +## Query Formulation + +- Rewrite the user question into a search-ready query. +- Generate two or three alternative queries for broader coverage. +- Add synonyms and related terms. +- Batch the queries in one action when the framework allows it. + +A code-based agent (CodeAct) can run several searches in one action. This cuts LLM calls by about 30 percent compared with one tool call per search. The ReAct loop (reason, act, observe) is the default pattern. + +## Extraction and Processing + +- Convert HTML to clean Markdown before you feed the model. Pi does this in `fetch_content`. +- Remove near-duplicate results across engines. +- Re-rank with BM25 relevance scoring. +- Keep a source reference for every extracted fact. +- Truncate long pages. A common cap is 40,000 characters per page. + +Use query-aware content filters to cut noise before the model sees text. Crawl4AI ships three filters: + +- `BM25ContentFilter` — score page chunks against the query. Keep only relevant snippets. +- `PruningContentFilter` — strip boilerplate by text and link density. +- `LLMContentFilter` — delegate filtering to a model for hard pages. + +Run BM25 re-ranking on the search results themselves. The SearXNG BM25 reranker plugin builds a temporary index and fuses BM25 scores with engine rankings using reciprocal rank fusion. This lifts keyword accuracy over raw engine order. + +## Respect Rate Limits + +Upstream engines and SearXNG block agents that hammer them. Slow down on purpose. + +- Respect `Retry-After` headers. +- Use exponential backoff on retries. +- Rotate user-agent strings. +- Add random delays between requests. +- Cap the request rate. A common default is 1 request per second. +- Run a circuit breaker that suspends a failing engine. +- Cache results with a time-to-live value. + +```yaml +# SearXNG side: cap timeouts and retries +outgoing: + request_timeout: 2.0 + max_request_timeout: 10.0 + retries: 3 +``` + +SearXNG suspends failing engines on a timer. For example, a CAPTCHA response suspends the engine for 3600 seconds. Respect that pause instead of retrying into the block. + +## Validate the Answer + +- Cross-reference each claim against a second independent source. +- Prefer primary sources over summaries. +- Record the authority and freshness of each source. + +Score credibility on concrete signals: + +- Domain type. Prefer `.edu`, `.gov`, and `.org` over personal `.com` sites. +- Link density. A low text-to-link ratio signals a content farm. +- Metadata. A real `` and author byline signal an authored page. +- Cross-reference. Re-fetch the URL and confirm that the claim appears in the content. + +## The Finish Rule + +An agentic loop must end. Decide in advance when enough evidence exists: + +1. You found consistent answers across two or more sources. +2. Your retrieval budget is spent. +3. The question is answered with the required confidence. + +Cap the loop. A common default is 20 steps for the search agent, with a plan re-check every 4 steps. If no source confirms a claim, say so. Do not smooth over the gap. + +## Citations + +- Smolagents ReAct guide: <https://huggingface.co/docs/smolagents/conceptual_guides/react> +- CodeAct paper: <https://arxiv.org/abs/2402.01030> +- Crawl4AI documentation: <https://docs.crawl4ai.com> +- Search result re-ranking, BM25 approach: <https://github.com/Oaklight/searxng-bm25-reranker> +- SearXNG outgoing settings: <https://docs.searxng.org/admin/settings/settings_outgoing.html> +- SearXNG limiter: <https://docs.searxng.org/admin/searx.limiter.html> + +## See Also + +- [Research Effectiveness](research-effectiveness.md) — Orchestrate the loop into a report. +- [SearXNG Tuning](searxng-tuning.md) — The backend behind the pipeline. +- [Self-Hosted Web Agents](self-hosted-web-agents.md) — The browser tools in the loop. diff --git a/omp-docs/agentic-web-research/index.md b/omp-docs/agentic-web-research/index.md new file mode 100644 index 0000000..4cdee48 --- /dev/null +++ b/omp-docs/agentic-web-research/index.md @@ -0,0 +1,39 @@ +# Agentic Web Research + +Agentic web research means that an AI drives the search loop. The agent formulates queries, reads results, decides what to read next, and writes a synthesis. It works best when search, extraction, and reasoning each run in the right place. + +> **Your setup:** Pi Web Access calls SearXNG at `192.168.0.143:8081` (dankclaw) and serves models through llama.cpp at `192.168.0.235:7770`, `192.168.0.143:7770`, and `localhost:8080`. The pages below assume that topology. + +This section connects four decisions: + +1. **Search backend** — make a self-hosted [SearXNG](searxng-tuning.md) instance fast and private. +2. **Network path** — send only SearXNG traffic through a [VPN](vpn-routing.md) and leave the rest alone. +3. **Agent loop** — apply [agentic search best practices](agentic-search-best-practices.md) and [research effectiveness](research-effectiveness.md) so the loop ends, not spins. +4. **Model choice** — pick a self-hostable [open model](open-models.md) strong enough for tool use and [web agents](self-hosted-web-agents.md). + +## Quick Map + +```mermaid +graph LR + A[User Question] --> B[Agent + Open Model] + B --> C[SearXNG Search] + C -->|VPN only here| D[Upstream Engines] + B --> E[Extraction: Crawl4AI / fetch] + B --> F[Synthesis + Citations] + E --> F +``` + +## Pages + +- [Self-Hosted Web Agents](self-hosted-web-agents.md) — Tools and architectures for an agent that drives a browser. +- [SearXNG Tuning](searxng-tuning.md) — Configuration for speed, privacy, and useful results. +- [VPN Routing for SearXNG](vpn-routing.md) — Route only the SearXNG outbound path through a VPN. +- [Agentic Search Best Practices](agentic-search-best-practices.md) — Query, extract, validate, and retry well. +- [Open Models for Web Use](open-models.md) — Self-hostable models strong at tool and API calling. +- [Research Effectiveness](research-effectiveness.md) — Multi-step, credibility-scored research loops. +- [Model Context Protocol](mcp.md) — The standard that connects the agent to tools. + +## Sources + +Authoritative references are cited per page under `# Citations`. + diff --git a/omp-docs/agentic-web-research/mcp.md b/omp-docs/agentic-web-research/mcp.md new file mode 100644 index 0000000..34aff35 --- /dev/null +++ b/omp-docs/agentic-web-research/mcp.md @@ -0,0 +1,95 @@ +--- +type: concept +title: Model Context Protocol (MCP) for Web Research +description: The standard way to connect an agent to search, fetch, and tool servers, and how it fits a self-hosted web research stack. +tags: + - mcp + - protocol + - tools + - agentic + - unverified +verified: 2026-08-28 +timestamp: 2026-08-11 +resource: https://modelcontextprotocol.io +--- + +# Model Context Protocol (MCP) for Web Research + +Model Context Protocol (MCP) is the open standard for connecting an AI model to external tools and data. Use it to give your agent search, page fetching, and database access without wiring each provider by hand. + +MCP uses a client-server model. The agent is an MCP client. Each capability runs in an MCP server. The agent calls the tools that the server exposes. + +The Linux Foundation hosts the project. The spec lives at `modelcontextprotocol.io`. + +## Transports + +MCP servers use one of two current transports: + +- `stdio` — the server runs as a child process. Good for local, single-client use. +- `Streamable HTTP` — a single HTTP POST endpoint. Good for remote or multi-client use. + +The older `HTTP+SSE` transport still works for compatibility. Clients auto-detect it. + +## The Model + +```mermaid +graph LR + A[Agent / MCP client] --> B[Search server] + A --> C[Fetch server] + A --> D[Database server] + A --> E[Filesystem server] +``` + +## Official Reference Servers + +The `modelcontextprotocol/servers` repository ships seven reference servers: + +| Server | Purpose | +|--------|---------| +| Fetch | Fetch and convert a web page | +| Filesystem | Read and write local files | +| Git | Read and manipulate Git repositories | +| Memory | Knowledge-graph persistent memory | +| Sequential Thinking | Reflective problem solving | +| Time | Answer time-related queries | +| Everything | Test and demo server | + +## Search Servers + +- The official **Brave Search MCP** server (`brave-search-mcp-server`) exposes `brave_web_search` and related tools. It needs a Brave API key. +- Community **SearXNG MCP** servers connect any SearXNG instance to MCP. They work with your self-hosted instance and need no API key. +- **Crawl4AI** ships a built-in MCP bridge in its Docker image that turns crawls into MCP tools. + +## Why It Matters Here + +- SmolAgents loads MCP tools with `ToolCollection.from_mcp()`. +- CrewAI integrates MCP through `MCPServerStdio`, `MCPServerHTTP`, and `MCPServerSSE`. +- Browser Use exposes MCP via `com.browser-use`. +- Qwen3 does agentic tool calling through the Qwen-Agent framework. + +With MCP, the search, fetch, and synthesis steps in this section share one connection standard. The agent does not depend on one vendor's format. + +## Run It Securely + +Follow these rules for a self-hosted MCP server: + +- Bind to `127.0.0.1` for local use. +- Prefer `stdio` transport for a local agent. +- Use Streamable HTTP with auth only for remote use. +- Validate the `Origin` header on HTTP servers. A mismatch must return HTTP 403. A bad check lets a remote site attack a local server. +- Treat tool descriptions as untrusted. They can carry prompt injection. + +## Citations + +- MCP specification: <https://modelcontextprotocol.io> +- Official MCP reference servers: <https://github.com/modelcontextprotocol/servers> +- Brave Search MCP server: <https://github.com/brave/brave-search-mcp-server> +- SearXNG MCP server (community): <https://github.com/aicrafted/searxng-mcp> +- SmolAgents repository: <https://github.com/huggingface/smolagents> +- Crawl4AI repository: <https://github.com/unclecode/crawl4ai> + +## See Also + +- [Agentic Search Best Practices](agentic-search-best-practices.md) — The loop MCP connects. +- [Self-Hosted Web Agents](self-hosted-web-agents.md) — Tools that expose MCP. +- [Open Models for Web Use](open-models.md) — Models that drive these tools. diff --git a/omp-docs/agentic-web-research/open-models.md b/omp-docs/agentic-web-research/open-models.md new file mode 100644 index 0000000..13b81ce --- /dev/null +++ b/omp-docs/agentic-web-research/open-models.md @@ -0,0 +1,90 @@ +--- +type: concept +title: Open Models for Web Use +description: Self-hostable, open-weight models that are strong at tool use, API calling, and internet-assisted tasks. +tags: + - open-models + - tool-use + - function-calling + - llm + - unverified +verified: 2026-08-28 +timestamp: 2026-08-11 +resource: https://qwenlm.github.io/blog/qwen3/ +--- + +# Open Models for Web Use + +The model is the brain behind the agent. For web research the model must call tools, follow instructions, and sometimes understand a page image. This page ranks the best self-hostable open-weight options. + +> **Your setup:** Pi already serves local models through llama.cpp. See [Llama.cpp Server](../tools/llama-cpp/index.md) and [Pi Models Configuration](../pi/models.md). You can run any of the picks below on those hosts. + +## The Front-Runner: Qwen3 (Alibaba, Apache 2.0) + +Qwen3 is the current state of the art for open function calling and tool use. It has a thinking / non-thinking hybrid mode and strong tool-calling. Release date: April 2025. + +| Model | Type | Active params | Context | Q4 VRAM | +|-------|------|---------------|---------|---------| +| Qwen3-8B | Dense | 8B | 128K | ~5 GB | +| Qwen3-14B | Dense | 14B | 128K | ~9 GB | +| Qwen3-32B | Dense | 32B | 128K | ~18 GB | +| Qwen3-30B-A3B | MoE | 3B | 128K | ~15 GB | + +The 8B and 14B models run on one consumer GPU. The 30B-A3B MoE runs on a single A100-class card or equivalent. + +## Best Vision Model: Qwen2.5-VL-7B + +Many web tasks need a model that can read a page image, not just text. Qwen2.5-VL-7B is the best open vision model for this. It reads text, charts, icons, and layout in screenshots. It supports computer-use and phone-use agents. Apache 2.0 license. The 7B model fits on a single GPU with 8 GB or more. + +Llama 4 Scout is the larger multimodal option. Verify the claims before you trust them: + +- "10 million token context" — true, but **Scout only**, not Maverick. +- "Fits on a single H100" — only true with INT4 quantization (about 48 GB). +- "Beats GPT-4o" — Meta's own release benchmarks, not independent runs. + +## Choose by Hardware + +```mermaid +graph TD + A[Consumer GPU 16-24GB] --> B[Qwen3-8B / 14B] + A --> C[Qwen2.5-VL-7B] + D[Single server GPU 80GB] --> E[Qwen3-30B-A3B] + D --> F[Llama 4 Scout INT4] + G[Multi-GPU cluster] --> H[Qwen3-235B-A22B] +``` + +## Serving Options + +- **llama.cpp** — CPU/GPU inference with GGUF quantization. Best for one consumer GPU. This is what Pi uses. +- **Ollama** — Easy local serving. Does not run in the Pi setup today. +- **vLLM** — High-throughput serving. Best for server and multi-GPU MoE models. +- **SGLang** — Strong for MoE serving. + +```bash +# On the Pi llama.cpp host +# Serve a downloaded GGUF with the OpenAI-compatible API +llama-server -m qwen3-8b-q4_k_m.gguf -c 131072 --port 7770 +``` + +## The Trade-Off + +| Need | Pick | +|------|------| +| Best tool calling, one consumer GPU | Qwen3-8B or 14B | +| Visually read a web page | Qwen2.5-VL-7B | +| Server-scale reliable agent | Qwen3-235B-A22B | +| Cheapest acceptable agent | Qwen3-8B on a mid GPU | + +## Citations + +- Qwen3 technical report: <https://qwenlm.github.io/blog/qwen3/> +- Qwen3 repository: <https://github.com/QwenLM/Qwen3> +- Qwen2.5-VL-7B model card: <https://huggingface.co/Qwen/Qwen2.5-VL-7B-Instruct> +- Meta AI Llama 4 announcement: <https://ai.meta.com/blog/llama-4-multimodal-intelligence/> +- Ollama library: <https://ollama.com/library> +- Browser Use supported models: <https://docs.browser-use.com/open-source/supported-models> + +## See Also + +- [Self-Hosted Web Agents](self-hosted-web-agents.md) — The tools these models drive. +- [Model Context Protocol (MCP)](mcp.md) — Connect tools to the model. diff --git a/omp-docs/agentic-web-research/research-effectiveness.md b/omp-docs/agentic-web-research/research-effectiveness.md new file mode 100644 index 0000000..f264fcf --- /dev/null +++ b/omp-docs/agentic-web-research/research-effectiveness.md @@ -0,0 +1,130 @@ +--- +type: concept +title: Research Effectiveness +description: Orchestrate a multi-step research loop — roles, credibility scoring, and when to stop. +tags: + - agentic + - research + - orchestration + - credibility + - unverified +verified: 2026-08-28 +timestamp: 2026-08-11 +--- + +# Research Effectiveness + +One model call does not make good research. A research pipeline assigns roles, scores sources, and stops when it has enough. This page explains how to build one. + +## Add Structure With Roles + +Split the work into roles. Each role has one job. + +```mermaid +graph LR + A[Researcher] --> B[Analyst] + B --> C[Writer] + C --> D[Critic] + D -->|gaps found| A + D -->|done| E[Final report] +``` + +| Role | Job | +|------|-----| +| Researcher | Search, extract pages, rank sources | +| Analyst | Extract facts, evaluate credibility | +| Writer | Synthesize and write the report | +| Critic | Find gaps and request follow-up | + +## Use a Manager and a Search Agent + +The strongest open recipe is a two-tier design: + +- A **manager** agent reasons and plans. It uses code actions and a plan that it re-checks every few steps. +- A **search agent** does the web browsing. It has its own bounded tool set and step cap. + +The search agent holds the browser tools: search, visit page, find on page, inspect files, and archive fallback. The manager reads results, decides what to follow next, and asks for a final answer when done. + +This pattern powers open deep-research systems. The open reproduction scores about 55 percent on GAIA, below the closed OpenAI version at 67 percent, but it runs fully on your own stack. + +## Score Source Credibility + +Score each source on a small set of signals: + +- Domain authority. +- Content freshness. +- Source diversity (independent sources agree). +- Whether other sources confirm the claim. + +Cross-reference each fact. If two independent sources agree, the fact is stronger. + +## Keep Context Small + +Never pass a full page to the model. + +- Convert HTML to Markdown and strip scripts and navigation. +- Split long pages into viewports and show one chunk at a time. +- Cap file text at a fixed size, for example 100,000 characters. +- Filter content before the model sees it. + +Smaller context means a faster loop and a lower chance of confusion. + +## Stop Hallucinated Citations + +An agent can invent a source. Guard against it: + +1. The agent returns answers with structured citations. +2. The manager re-fetches each cited URL. +3. If a citation fails, the agent re-searches with a modified query. + +Use a web archive as a fallback for dead links. + +## Adapt the Search + +Do not follow every link. Follow the links that the question needs. Stop when the confidence threshold passes. Tools such as Crawl4AI expose an adaptive crawler that reports its own confidence. + +## Choose an Orchestration Tool + +| Tool | Best for | Notes | +|------|----------|-------| +| CrewAI | Role-based multi-agent work | Sequential or hierarchical processes | +| LangGraph | Stateful, long-running research | Durable execution, human in the loop | +| SmolAgents | Simple code-based agents | MCP support, manager + search agent | +| Qwen-Agent | Qwen model + MCP tools | Best integration with Qwen3 | + +Pi already runs a similar model with its parallel `researcher` and `scout` subagents. + +## The Finish Rule + +Research must end. Stop when any one is true: + +1. Two or more independent sources agree on the answer. +2. The retrieval budget is spent. +3. The required confidence is met for every claim. + +Report gaps honestly. Do not invent a source to fill one. + +## Failure Modes and Guardrails + +Agentic loops fail in predictable ways. Add guardrails up front. + +| Failure | Guardrail | +|---------|-----------| +| Hallucinated citation | Cite structured objects, then re-fetch each URL | +| Search engine block | Respect retry-after, use adaptive rate limiting, read the ban time | +| Infinite re-search | Cap search rounds, reject near-duplicate queries, re-plan every few steps | +| Context overflow | Filter content before the model sees it, track the token budget | + +## Citations + +- Smolagents open deep research: <https://huggingface.co/blog/open-deep-research> +- Smolagents multiagents guide: <https://huggingface.co/docs/smolagents/examples/multiagents> +- CrewAI repository: <https://github.com/crewAIInc/crewAI> +- CrewAI documentation: <https://docs.crewai.com/> +- LangGraph repository: <https://github.com/langchain-ai/langgraph> +- Crawl4AI documentation: <https://docs.crawl4ai.com> + +## See Also + +- [Agentic Search Best Practices](agentic-search-best-practices.md) — The loop this orchestrates. +- [Open Models for Web Use](open-models.md) — The model that runs each role. diff --git a/omp-docs/agentic-web-research/searxng-tuning.md b/omp-docs/agentic-web-research/searxng-tuning.md new file mode 100644 index 0000000..206548b --- /dev/null +++ b/omp-docs/agentic-web-research/searxng-tuning.md @@ -0,0 +1,194 @@ +--- +type: concept +title: SearXNG Tuning +description: Configuration decisions for a fast, private, useful self-hosted SearXNG instance. +tags: + - searxng + - search + - privacy + - configuration + - unverified +verified: 2026-08-28 +timestamp: 2026-08-11 +resource: https://docs.searxng.org +--- + +# SearXNG Tuning + +SearXNG is a metasearch engine. It aggregates 274 or more upstream search services into one result set. Configuration lives in `settings.yml`. The recommended deployment is Docker Compose with a Valkey container. + +This page lists the settings that matter for speed, privacy, and useful results. + +> **Your setup:** Pi Web Access calls a remote SearXNG at [`192.168.0.143:8081`](../pi/packages/pi-web-access.md) (dankclaw). Apply these settings to that host, not to this machine. + +## Plan the Deployment + +```mermaid +graph LR + A[Browser or Agent] --> B[SearXNG container] + B --> C[Valkey cache + limiter] + B --> D[Engine request pool] + D --> E[Google News] + D --> F[DuckDuckGo] + D --> G[Wikipedia] +``` + +Deploy with the official Docker Compose file. It ships a `searxng-valkey` container (`valkey/valkey:9-alpine`). Valkey replaced Redis as the default cache. Mount your config at `./core-config/:/etc/searxng`. + +```yaml +services: + searxng: + image: docker.io/searxng/searxng:latest + ports: + - "8081:8080" + volumes: + - ./core-config/:/etc/searxng/:Z + depends_on: + - searxng-valkey + + searxng-valkey: + image: docker.io/valkey/valkey:9-alpine + restart: always +``` + +## Core Settings + +```yaml +use_default_settings: true +server: + secret_key: "change-this" # or $SEARXNG_SECRET + base_url: "http://192.168.0.143:8081/" # or $SEARXNG_BASE_URL + limiter: true + method: "POST" + +search: + default_lang: "en" + default_locale: "en-US" + safe_search: 0 + formats: + - html + - json +``` + +Change `secret_key`. Set `base_url` to the public address. Use `POST` for privacy. Enable the `json` format for the agent. + +## Rate Limiting + +Enable the limiter and point it at Valkey. Without a limiter, an upstream engine can block SearXNG's IP. + +```yaml +server: + limiter: true + +valkey: + url: valkey://searxng-valkey:6379/0 +``` + +The limiter uses a sliding window per IP: + +| Window | HTML limit | JSON/API limit | +|--------|-----------|----------------| +| 20 seconds | 15 | 4 per 3600 s | +| 600 seconds | 150 | 4 per 3600 s | + +Suspicious IPs get a much lower budget (2 in 20 s, 10 in 600 s). The agent that hits the JSON endpoint repeatedly can trip the 4-per-hour API limit. Back off or make the agent part of a trusted group. + +## Outgoing Pool + +```yaml +outgoing: + request_timeout: 3.0 + max_request_timeout: 10.0 + pool_connections: 100 + pool_maxsize: 20 + enable_http2: true + keepalive_expiry: 5.0 + retries: 3 +``` + +A short `request_timeout` keeps results snappy. `enable_http2` multiplexes connections. More `retries` makes results more reliable but slower. + +## Engine Selection + +Default engine state (current SearXNG): + +| Engine | Default state | Note | +|--------|---------------|------| +| DuckDuckGo | Enabled | Reliable general search | +| Wikipedia | Enabled | Encyclopedia lookups | +| Google News | Enabled | News results | +| Google (main) | Inactive | Cloudflare CAPTCHA often blocks it | +| Bing | Disabled | Blocked upstream | + +Keep only the engines you need. Fewer engines means faster responses. + +```yaml +use_default_settings: + engines: + keep_only: + - duckduckgo + - wikipedia + - google news +``` + +Make an engine private to one agent with a token: + +```yaml +engines: + - name: arch wiki + engine: archlinux + tokens: ['my-secret-token'] +``` + +## Useful Plugins + +```yaml +plugins: + searx.plugins.unit_converter.SXNGPlugin: + active: true + searx.plugins.calculator.SXNGPlugin: + active: true + searx.plugins.self_info.SXNGPlugin: + active: true +``` + +The hostnames plugin filters or rewrites results. It needs a separate `hostnames:` block: + +```yaml +hostnames: + remove: + - '(.*\.)?facebook.com$' + high_priority: + - '(.*\.)?wikipedia.org$' +``` + +## JSON API for the Agent + +The agent uses the JSON format. Confirm that it returns structured data: + +```bash +curl 'http://192.168.0.143:8081/search?q=test&format=json' +``` + +The response contains `results`, `query`, `number_of_results`, and `suggestions`. The `/config` endpoint lists engine availability. + +## Verify the Instance + +1. Open the HTML interface and run a test query. +2. Confirm that the `json` format returns data. +3. Confirm that the limiter page appears on rapid repeats. + +## Citations + +- SearXNG documentation: <https://docs.searxng.org> +- SearXNG outgoing settings: <https://docs.searxng.org/admin/settings/settings_outgoing.html> +- SearXNG engine settings: <https://docs.searxng.org/admin/settings/settings_engines.html> +- SearXNG Valkey settings: <https://docs.searxng.org/admin/settings/settings_valkey.html> +- SearXNG limiter: <https://docs.searxng.org/admin/searx.limiter.html> +- SearXNG plugins: <https://docs.searxng.org/admin/settings/settings_plugins.html> +- Docker Compose install: <https://docs.searxng.org/admin/installation-docker.html> + +## See Also + +- [VPN Routing for SearXNG](vpn-routing.md) — Route the outbound path through a VPN. +- [Agentic Search Best Practices](agentic-search-best-practices.md) — Use the JSON format well. diff --git a/omp-docs/agentic-web-research/self-hosted-web-agents.md b/omp-docs/agentic-web-research/self-hosted-web-agents.md new file mode 100644 index 0000000..8803c88 --- /dev/null +++ b/omp-docs/agentic-web-research/self-hosted-web-agents.md @@ -0,0 +1,106 @@ +--- +type: concept +title: Self-Hosted Web Agents +description: Tools and architectures that let an AI agent drive a real browser, self-hosted. +tags: + - agentic + - browser + - scraping + - web-agent + - unverified +verified: 2026-08-28 +--- + +# Self-Hosted Web Agents + +A web agent is an AI that controls a browser. It sees the page, chooses an action, and repeats until it completes the task. You can run the whole loop on your own hardware. + +This page covers the leading open tools and the architecture the agent uses. + +## The Main Tools + +### Browser Use + +Browser Use is a Python library that uses Playwright under the hood. It is MIT-licensed. It supports many model providers, including local OpenAI-compatible endpoints such as llama.cpp. + +Key ideas: + +- It snapshots the DOM and converts it to Markdown for the model. +- Ten watchdogs handle CAPTCHAs, crashes, popups, downloads, and security. +- Real browser profiles carry saved logins. + +**On the "87.4 percent" number:** that result refers to Browser Use's managed Cloud agent (the Hybrid type that blends structured browser tools with screenshots). Peer-reviewed results for vision-only (CUA) models are much lower, about 44.5 percent on the same task type. Treat any single accuracy number as one benchmark, not a universal score. + +```python +# Local model via llama.cpp (OpenAI-compatible endpoint) +from browser_use import Agent +from browser_use.llm.openai import ChatOpenAI + +agent = Agent( + task="Search for the latest AI news", + llm=ChatOpenAI( + base_url="http://192.168.0.235:7770/v1", + model="frank-default-small", + api_key="EMPTY", + ), +) +await agent.run() +``` + +### Skyvern + +Skyvern is an open-source browser agent (AGPL-3.0). It uses a vision model to see the page and Playwright to act. It extends Playwright with `page.act()`, `page.extract()`, and `page.validate()`. It ships a Docker Compose setup. Use it when you need a vision-first agent. + +### Crawl4AI + +Crawl4AI is an async crawler that returns LLM-friendly Markdown. It is built for retrieval pipelines, not for clicking through interactive pages. Use it to fetch and clean many pages quickly. + +Key ideas: + +- It produces clean Markdown and a noise-filtered "fit Markdown." +- It supports deep crawling with breadth-first, depth-first, and best-first strategies. +- It can run in Docker with a REST API and MCP endpoints. + +```bash +pip install -U crawl4ai +crawl4ai-setup +crwl https://example.com --deep-crawl bfs --max-pages 10 +``` + +## The Loop + +```mermaid +graph TD + A[Task] --> B[Model chooses action] + B --> C[Browser or Crawler acts] + C --> D[Extract text / Markdown] + D --> B + D --> E[Task done?] + E -->|No| B + E -->|Yes| F[Return answer + citations] +``` + +## Which Tool to Use + +| Situation | Tool | +|-----------|------| +| Need to click, log in, or fill forms | Browser Use | +| Need vision-based browsing | Skyvern | +| Need to fetch and clean many static pages | Crawl4AI | +| Research pipeline feeds an agent | Crawl4AI first, Browser Use for interactive steps | + +A hybrid works best. Use Crawl4AI for mass extraction and Browser Use for the interactive steps. + +## Citations + +- Browser Use repository: <https://github.com/browser-use/browser-use> +- Browser Use documentation: <https://docs.browser-use.com> +- Skyvern repository: <https://github.com/Skyvern-AI/skyvern> +- Crawl4AI repository: <https://github.com/unclecode/crawl4ai> +- Crawl4AI documentation: <https://docs.crawl4ai.com> + +## See Also + +- [Agentic Search Best Practices](agentic-search-best-practices.md) — The loop around the tools. +- [Open Models for Web Use](open-models.md) — Models that drive these tools. +- [Research Effectiveness](research-effectiveness.md) — Orchestration around the loop. diff --git a/omp-docs/agentic-web-research/vpn-routing.md b/omp-docs/agentic-web-research/vpn-routing.md new file mode 100644 index 0000000..5c274df --- /dev/null +++ b/omp-docs/agentic-web-research/vpn-routing.md @@ -0,0 +1,189 @@ +--- +type: concept +title: VPN Routing for SearXNG +description: Send only SearXNG outbound requests through a VPN while leaving all other local traffic alone. +tags: + - vpn + - searxng + - networking + - proxy + - unverified +verified: 2026-08-28 +timestamp: 2026-08-19 +resource: https://docs.searxng.org/admin/settings/settings_outgoing.html +--- + +# VPN Routing for SearXNG + +SearXNG talks to many upstream engines. Some of them rate-limit or block the source IP. You can send only that outbound path through a VPN and leave every other process on the host untouched. + +This page gives four working patterns. Choose the one that matches how you run SearXNG. + +> **Your setup:** SearXNG runs on another host at `192.168.0.143:8081` (dankclaw). Apply the Docker patterns on that host. The proxy pattern works from any host. + +## The Goal + +```mermaid +graph LR + A[Local agent] --> B[SearXNG] + B -->|through VPN| C[Upstream engines] + D[Other local traffic] --> E[Plain internet] +``` + +The VPN carries only the SearXNG outbound path. Nothing else changes. + +## Pattern 1: SearXNG Proxy Setting + +SearXNG supports HTTP and SOCKS proxies natively. Point the outbound settings at a local proxy that exits through the VPN. + +```yaml +outgoing: + proxies: + all://: + - socks5://vpn-proxy:1080 + extra_proxy_timeout: 10.0 +``` + +Apply the proxy to one engine only: + +```yaml +engines: + - name: google + engine: google + proxies: + https: + - socks5://vpn-proxy:1080 +``` + +To force the VPN source IP on a multi-homed host, add `source_ips` and pin the engine to IPv4: + +```yaml +outgoing: + source_ips: + - 10.8.0.2 + +engines: + - name: my-search + engine: duckduckgo + network: ipv4 +``` + +## Pattern 2: Gluetun (Recommended) + +Gluetun is a VPN container (WireGuard or OpenVPN). Attach SearXNG to its network namespace. Only SearXNG shares the tunnel. Other containers stay on the default network. + +```yaml +services: + gluetun: + image: qmcgaw/gluetun:latest + cap_add: [NET_ADMIN] + devices: [/dev/net/tun:/dev/net/tun] + ports: + - "8081:8080" + environment: + VPN_SERVICE_PROVIDER: mullvad + VPN_TYPE: wireguard + WIREGUARD_PRIVATE_KEY: <key> + restart: always + + searxng: + image: searxng/searxng:latest + network_mode: service:gluetun + depends_on: + - gluetun + volumes: + - ./core-config:/etc/searxng + restart: unless-stopped +``` + +Put the port mapping on the `gluetun` service. The `searxng` container does not get its own ports. + +## Pattern 3: Dedicated Internal Network + +Create a network that only SearXNG shares with a lighter VPN client. + +```yaml +services: + searxng: + image: searxng/searxng:latest + networks: + - searxng-vpn + volumes: + - ./core-config:/etc/searxng + + vpn-client: + image: dperson/openvpn-client:latest + networks: + - searxng-vpn + cap_add: + - NET_ADMIN + +networks: + searxng-vpn: + internal: true +``` + +An OpenVPN client container is simpler than Gluetun when your provider uses OpenVPN. + +## Pattern 4: Run SearXNG Inside the VPN Container + +```yaml +services: + searxng: + image: searxng/searxng:latest + network_mode: "container:vpn-client" + depends_on: + - vpn-client + volumes: + - ./core-config:/etc/searxng + + vpn-client: + image: dperson/openvpn-client:latest + cap_add: [NET_ADMIN] + environment: + VPN: server.address;username;password + restart: always +``` + +This pattern places the whole SearXNG process inside the tunnel namespace. The host sees the tunnel as the only route for SearXNG. + +## Compare the Patterns + +| Pattern | Complexity | Isolation | Per-engine control | +|---------|-----------|-----------|--------------------| +| Proxy setting | Low | Medium | Yes | +| Gluetun | Medium | High | No | +| Dedicated network | Medium | High | No | +| Inside VPN container | Medium | Highest | No | + +## Decisions That Matter + +- A SOCKS proxy keeps the per-engine control. Use Pattern 1. +- Gluetun gives the cleanest full-tunnel setup. Use Pattern 2. +- Mullvad ships its own WireGuard keys for Gluetun. +- An OpenVPN-only provider works with Pattern 3 or 4. + +## Verify the Route + +1. Run the instance with the VPN active. +2. Query an IP-echo page through SearXNG. +3. Confirm that the returned IP differs from your host IP. +4. Confirm that unrelated host traffic keeps the host IP. + +```bash +# From inside the tunnel with Gluetun +docker exec gluetun curl -s ifconfig.me +``` + +## Citations + +- SearXNG outgoing settings: <https://docs.searxng.org/admin/settings/settings_outgoing.html> +- SearXNG engine settings: <https://docs.searxng.org/admin/settings/settings_engines.html> +- Gluetun: <https://github.com/qdm12/gluetun> +- Connect a container to Gluetun: <https://github.com/qdm12/gluetun-wiki/blob/main/setup/connect-a-container-to-gluetun.md> +- Docker Compose networking: <https://docs.docker.com/compose/networking/> + +## See Also + +- [SearXNG Tuning](searxng-tuning.md) — The instance these patterns protect. +- [Agentic Search Best Practices](agentic-search-best-practices.md) — Proxy rotation and retries. diff --git a/omp-docs/caddy/caddyfile.md b/omp-docs/caddy/caddyfile.md new file mode 100644 index 0000000..67f97e4 --- /dev/null +++ b/omp-docs/caddy/caddyfile.md @@ -0,0 +1,249 @@ +--- +type: reference +title: Caddyfile Syntax +description: Caddy Caddyfile reference — directive and matcher syntax, named matchers, directive sorting, and the handle/route order rule. Grounded in caddyserver.com (fetched 2026-08-28). +resource: https://caddyserver.com/docs/caddyfile +tags: + - caddy + - caddyfile + - reverse-proxy +verified: 2026-08-28 +--- + +# Caddyfile Syntax + +A Caddyfile defines sites. Each site block starts with an address (a host or a +port). Directives inside the block control how Caddy serves requests. Matchers +classify requests. This page records the syntax that trips people up, grounded +in the official docs. + +Sources: [caddyfile-tutorial](https://caddyserver.com/docs/caddyfile-tutorial), +[matchers](https://caddyserver.com/docs/caddyfile/matchers), +[rewrite](https://caddyserver.com/docs/caddyfile/directives/rewrite), +[handle](https://caddyserver.com/docs/caddyfile/directives/handle), +[forward_auth](https://caddyserver.com/docs/caddyfile/directives/forward_auth), +[reverse_proxy](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy), +[concepts](https://caddyserver.com/docs/caddyfile/concepts). + +## Directive and matcher syntax + +A directive takes an optional matcher as its **first argument**: + +``` +directive [<matcher>] <args...> +``` + +The matcher token is one of three forms: + +* `*` — the wildcard (matches all requests). +* `/path` — a path (must start with `/`). +* `@name` — a named matcher. + +The matcher follows the directive name. A leading `@name` before a directive +name is parsed as a **matcher definition**, not a use (see below). + +## Named matchers + +A named matcher is defined outside any directive and reused: + +``` +@name { + <matchers...> +} +``` + +If the set has one matcher, a one-liner works: + +``` +@post method POST +``` + +Use the matcher as the first argument of a directive: + +``` +reverse_proxy @post localhost:6001 +``` + +**Pitfall:** `@name <directive>` (the `@name` before the directive) is parsed +as a one-liner **definition** of `@name`. Writing it twice re-defines the +matcher and Caddy rejects the config with `matcher is defined more than once`. +Always put the matcher after the directive: `rewrite @name /to`, not +`@name rewrite /to`. + +## Path matching + +Path matching is an **exact** match by default. Append `*` for a prefix match: + +* `/foo*` matches `/foo`, `/foo/`, and `/foobar`. +* `/foo/*` matches `/foo/` and `/foo/anything`, but not `/foo` or `/foobar`. + +A `handle` inline matcher is a **single token**. To match several paths, use a +named matcher: + +``` +@data path /a.json /b.js +handle @data { ... } +``` + +## Directive sorting (the key rule) + +Caddy **sorts** top-level directives by a fixed canonical order. It does not +run them in file order. The relevant order (partial): `vars`, `root`, +`redir`, then `rewrite`, `try_files`, `uri`, then `basic_auth`, then +`file_server`. + +**Consequence:** a top-level `rewrite` runs **before** a top-level +`basic_auth`. If the rewrite changes the path, the path-based auth matcher sees +the **rewritten** path, not the original. This silently applies the wrong +auth block. + +**Fix:** wrap the ordered directives in `handle` or `route`. These blocks run +their contents in **file order** (no re-sort). + +## handle vs route + +* `handle [<matcher>] { ... }` — mutually exclusive. Only the **first** matching + `handle` runs. A `handle` with no matcher is the catch-all. +* `route [<matcher>] { ... }` — runs its contents as one unit, in file order, + and the request continues to later top-level directives. + +Use `handle` for mutually exclusive branches (for example, per-path pages). Use +`route` when several directives must all run in order. + +## rewrite + +``` +rewrite [<matcher>] <to> +``` + +`<to>` is the new URI (path or query). If `<to>` starts with `/`, Caddy 2.8.0+ +parses it directly. Before 2.8.0, a leading `/` was confused with a path +matcher, so a `*` disambiguator was needed: `rewrite * /index.html`. + +`try_files <files...>` rewrites to the first listed file that exists. It is the +clean way to serve a named file for a path prefix: + +``` +try_files /admin.html +file_server +``` + +## file_server and root + +``` +root * /srv/site +file_server +``` + +`root` sets the site root. `file_server` serves files from the root by +appending the request path. The `*` is the wildcard matcher (it disambiguates +the path argument). + +## basic_auth + +``` +basic_auth [<matcher>] { + <username> <bcrypt_hash> + ... +} +``` + +The default hash algorithm is bcrypt. A block may list several users; any of +them is accepted. `basicauth` is deprecated in favor of `basic_auth`, but both +work. + +## forward_auth + +`forward_auth` is Caddy's auth gate for an external identity provider (OIDC, +Authelia, Authentik, Tailscale, ...). It clones the incoming request, sends it +to an auth upstream, and only proxies to the app if the upstream answers `2xx`. + +``` +forward_auth [<matcher>] [<upstreams...>] { + uri <to> + copy_headers <fields...> + trusted_proxies [private_ranges] <ranges...> +} +``` + +* `<upstreams...>` — the auth gateway address (positional, required). +* `uri <to>` — the path the cloned request hits on the gateway (the + verification endpoint, e.g. `/outpost.goauthentik.io/auth/caddy`). +* `copy_headers <fields...>` — header fields to copy from the gateway's `2xx` + response onto the proxied request (e.g. `X-Authentik-Username`). +* All `reverse_proxy` subdirectives pass through, including `trusted_proxies`. +* `trusted_proxies` accepts CIDRs or the keyword `private_ranges` (all private + ranges). It controls which sources Caddy trusts for `X-Forwarded-*`. + +**Pitfall — the outpost path:** an embedded outpost (Authentik) serves its own +login UI at a path (e.g. `/outpost.goauthentik.io/*`). That path must be +proxied to the gateway **before** `forward_auth` runs, or the login page is +itself gated. Wrap both in a `route` (file order), outpost first: + +``` +example.com { + route { + reverse_proxy /outpost.goauthentik.io/* authentik:9000 + forward_auth authentik:9000 { + uri /outpost.goauthentik.io/auth/caddy + copy_headers X-Authentik-Username X-Authentik-Groups + trusted_proxies private_ranges + } + reverse_proxy app:8080 + } +} +``` + +The `reverse_proxy` on the outpost path is terminal: a matched request proxies +to the gateway and the route stops. Non-outpost paths fall through to +`forward_auth`, then the app. + +## Worked example: per-path auth with shared data + +Serve `/admin/` (operator only) and `/` (family), where both pages fetch the +same data files. The browser reuses the page's credential for the data +fetches, so the data block must accept **both** users. + +``` +example.com { + root * /srv/site + + # Operator-only page. Auth is checked on the original path, before any + # rewrite, so the path matcher is reliable. + handle /admin* { + basic_auth { + frank $2a$14$<operator_hash> + } + try_files /admin.html + file_server + } + + # Shared data + assets: the family OR the operator. + @data path /services.json /status.json /app.js /style.css + handle @data { + basic_auth { + dank $2a$14$<family_hash> + frank $2a$14$<operator_hash> + } + file_server + } + + # Everything else: the family. + handle { + basic_auth { + dank $2a$14$<family_hash> + } + try_files /index.html + file_server + } +} +``` + +`handle` blocks run in file order and are mutually exclusive (first match +wins). Put the specific `handle /admin*` before the catch-all `handle`. + +## Validate before you deploy + +Run `caddy validate --config <file> --adapter caddyfile` before loading a +Caddyfile. A placeholder hash (not a real bcrypt hash) fails validation with +`base64-decoding password`. Render the real hashes first, then validate. diff --git a/omp-docs/caddy/index.md b/omp-docs/caddy/index.md new file mode 100644 index 0000000..db5bfee --- /dev/null +++ b/omp-docs/caddy/index.md @@ -0,0 +1,30 @@ +# Caddy + +Caddy is the reverse proxy and TLS terminator for the homelab. A single caddy +container on dankclaw (192.168.0.143) fronts every service on both hosts. It +runs Caddy v2.11.4 from the custom `franksdank/caddy-porkbun` image +(xcaddy-built with the Porkbun DNS-01 module, built locally on dankclaw). +Since 2026-08-26 it is managed as a Podman Quadlet unit (`caddy.container`) +installed to `~/.config/containers/systemd/`, providing boot-persistent, +auto-restart service management. + +* [[caddyfile|caddyfile]] — directive and matcher syntax, named matchers, + directive sorting, and the `handle`/`route` order rule. + +The Caddyfile lives in the serverAppConfigs repo at +`dankclaw/Caddyfile`. `deploy.sh` renders basicauth hashes from the host `.env` +(`REPLACE_WITH_HASH` → real bcrypt) into +`/home/dank/Containers/caddy/Caddyfile`, which the container mounts read-only; +Caddy's config file watcher (admin API, not disabled) hot-reloads on change. +The Caddyfile joins the `dankclaw_default` compose network so container-name +upstreams (authentik-server, grafana, etc.) still resolve. + +TLS: Let's Encrypt wildcard certs via Porkbun DNS-01. The `acme_dns` block in +the Caddyfile reads API keys from `/home/dank/Containers/caddy/env` (deployed +from the repo's git-ignored `.env`). No inbound port 80/443 reachability is +needed from the internet — DNS-01 works entirely from the LAN, where Pi-hole +resolves `*.franksdank.cloud` names to dankclaw. + +The porkbun DNS module source: [caddy-dns/porkbun](https://github.com/caddy-dns/porkbun). + +* [Caddyfile Syntax](caddyfile.md) — Caddy Caddyfile reference — directive and matcher syntax, named matchers, directive sorting, and the handle/route order rule. Grounded in caddyserver.com (fetched 2026-08-28). diff --git a/omp-docs/core/agents-md-format.md b/omp-docs/core/agents-md-format.md new file mode 100644 index 0000000..5d94fcf --- /dev/null +++ b/omp-docs/core/agents-md-format.md @@ -0,0 +1,196 @@ +--- +type: reference +title: AGENTS.md Format Specification +description: Canonical structure and conventions for the system-level instruction file that governs agent behavior during configuration sessions. +tags: + - agents-md + - configuration + - progressive-disclosure + - core-contract + - unverified +timestamp: 2026-01-15 +--- + +# AGENTS.md Format Specification + +This document defines the canonical structure and conventions for the `AGENTS.md` file located at `/home/dank/.pi/AGENTS.md`. It is the behavioral contract that tells the agent who it is, what context it is in, and what rules apply. + +--- + +## Purpose + +`AGENTS.md` is a **progressive disclosure instruction file**. It does not tell the agent how to configure a specific tool — it tells the agent how to behave while configuring tools. Think of it as the difference between a recipe and a cookbook. The recipe tells you what to do with eggplant. The cookbook tells you how to think about cooking. + +--- + +## Structure + +The file follows a strict top-to-bottom structure: + +``` +# Title — Context Label +## Context Declaration +## Your Role: Persona +## Progressive Disclosure (header) +--- +### Layer N: <Title> +<Content> +--- +### Layer N+1: <Title> +<Content> +--- +## Summary +``` + +### Section Order (Mandatory) + +| Order | Section | Description | +|-------|---------|-------------| +| 1 | `# Title — Context Label` | One-line title with context label in em-dash. Example: `AGENTS.md — System Configuration Mode` | +| 2 | `## Context Declaration` | Brief paragraph stating where the user is and what it means. Must mention the directory path. | +| 3 | `## Your Role: <Persona>` | Persona definition with bullet-point traits. Keep it tight — 4-6 bullets max. | +| 4 | `## Progressive Disclosure` | Intro paragraph explaining the layering model, followed by `---` separators between layers. | +| 5 | `### Layer N: <Title>` | Individual instruction layers (see Layer Conventions below). | +| 6 | `## Summary` | Compact table of all layers as quick-reference rows. | + +--- + +## Layer Conventions + +### Naming + +- Layers are numbered sequentially starting from 1. +- Use decimal sub-numbers for inserted layers (for example, `Layer 1.5`) to preserve ordering when new layers are added between existing ones. +- Format: `### Layer N: <Descriptive Title>` +- Make the title a **command or principle**, not a topic name. Prefer: + - `Verify Before You Commit — Deterministic Check First` + - `The Mandatory Documentation Fetch Protocol` + - NOT `Documentation` + - NOT `Package Installation` + +### Content Structure + +Give each layer this content: + +1. **Opening callout** (if the rule is critical): Bold `**This is non-negotiable.**` or `**MANDATORY:**` prefix. +2. **Definition**: What the rule/concept is. One paragraph, plain English. +3. **Workflow or steps**: Numbered lists for procedural instructions. +4. **Examples**: Code blocks, commands, or concrete scenarios. +5. **Scope**: When the rule applies (and when it does not). +6. **Common mistakes** (optional): `❌` prefixed anti-patterns. +7. **Correct behavior** (optional): `✅` prefixed patterns. + +### Layer Ordering Principle + +Layers are ordered by **priority and dependency**, not alphabetical: + +1. **Context layers** first (who you are, where you are) +2. **Pre-flight / safety layers** next (verification, documentation checks) +3. **Domain-specific layers** after that (tool rules, package rules, etc.) +4. **Emergency / fallback layers** last + +A layer that gates another layer must come before the layer it gates. (for example, "check docs exist" comes before "fetch docs if missing".) + +--- + +## Summary Table Conventions + +The `## Summary` section at the bottom is a **quick-reference table** that maps each layer to its action. + +### Format + +```markdown +## Summary + +| Context | Action | +|---------|--------| +| <Short layer title> | **<One-line action>** — <Optional detail>. | +``` + +### Rules + +- Every layer must have exactly one row in the summary. +- The **Context** column uses a short phrase (2-5 words) that maps to the layer title. +- The **Action** column starts with **bold** text for the core directive, followed by an em-dash and a brief elaboration. +- Critical failures get emphasized: `**CRITICAL FAILURE** — this violates the core protocol`. +- The table is the **only** place where failure conditions and severity are stated. +- Rows are ordered to match layer numbering. + +--- + +## Section Formatting + +### Code Blocks + +- Use triple backtick code blocks for commands, scripts, and configuration examples. +- Specify the language for syntax highlighting: ````bash`, ````json`, ````text`. +- Include inline comments in code blocks explaining what is right vs. wrong. +- Use `# CORRECT` and `# WRONG` comment labels for contrast examples. + +### Lists + +- Use **numbered lists** for sequential steps (workflows, protocols). +- Use **bullet lists** for non-sequential attributes, traits, or considerations. +- Use `❌` and `✅` prefixed bullets for anti-patterns vs. correct patterns. + +### Emphasis + +- Use `**bold**` for critical directives and failure conditions. +- Use `**bold**` in the Summary table for the core action phrase. +- Use backticks for file paths, commands, and config keys. +- Use `>` blockquotes sparingly — reserved for ASCII workflow diagrams. + +### ASCII Workflow Diagrams + +For critical decision flows, use ASCII art inside blockquotes: + +``` +User Request → Check index.md → Docs exist? → YES: Proceed + ↓ + NO: STOP → Fetch → Verify → Proceed +``` + +--- + +## Adding New Layers + +When adding a new behavioral rule: + +1. **Determine placement**: Where does this layer fit in the priority/dependency order? +2. **Assign a number**: If inserting between existing layers, use a decimal (for example, `Layer 2.5`). If appending, use the next integer. +3. **Write the layer** following the Content Structure conventions above. +4. **Add a summary row**: Insert a matching row in the Summary table at the correct position. +5. **Verify ordering**: Ensure the layer order matches the dependency chain (gating layers before gated layers). + +--- + +## What NOT to Include + +| Do Not | Why | +|--------|-----| +| Tool-specific configuration syntax | That belongs in `/docs/tools/<tool-name>/` | +| Long reference tables | Keep the Summary table concise; details belong in layer content | +| More than 10 layers | If you need more, the file is too big — consider splitting or consolidating | +| Narrative prose | Make every sentence actionable or declarative | +| Personal opinions or preferences | This is a system contract, not a blog post | + +--- + +## File Metadata + +| Property | Value | +|----------|-------| +| Path | `/home/dank/.pi/AGENTS.md` | +| Format | Markdown (GitHub Flavored) | +| Max layers | 10 (soft limit) | +| Max file size | ~15 KB (soft limit — if larger, consolidate) | +| Encoding | UTF-8 | +| Line endings | Unix (LF) | + +--- + +## Revision History + +| Version | Date | Change | +|---------|------|--------| +| 1.0 | 2026-07-09 | Initial specification — defines structure, layer conventions, summary format, and add/remove procedures | diff --git a/omp-docs/core/index-doc.md b/omp-docs/core/index-doc.md new file mode 100644 index 0000000..5abc3e7 --- /dev/null +++ b/omp-docs/core/index-doc.md @@ -0,0 +1,75 @@ +--- +type: reference +title: AGENTS.md Index +description: Overview of the cached tool documentation system — how it works, why the pre-flight check matters, and how to add new entries. +tags: + - documentation + - index + - pre-flight-check + - meta +timestamp: 2026-01-15 +--- + +# pi Documentation Index + +This directory (`/home/dank/.pi/agent/docs/`) contains cached documentation for tools used during system configuration. It is the agent's primary reference before touching any configuration file. + +--- + +## How to Use + +Before configuring any tool, check whether documentation already exists here. If it does not, a subagent **must** be spawned to fetch documentation before proceeding. + +This is not a suggestion. It is the difference between "I remember how to configure this" and "I will need to re-read the docs for the third time this week." + +--- + +## Available Tool Documentation + +### Core + +* [AGENTS.md Format](agents-md-format.md) — Structure specification for the system-level instruction file: layer conventions, naming, summary table format, and add/remove procedures. + +### Tools + +* [Ghostty Terminal](../tools/ghostty/index.md) — GPU-accelerated terminal emulator. Complete configuration reference with 100+ options organized by category, CLI actions, keybindings, shaders, and default bindings. +* [llama.cpp Server](../tools/llama-cpp/index.md) — LLM inference server. GGUF format, build guides (CPU/CUDA/Metal/Vulkan), server CLI options, API endpoints, Docker setup, and curl examples. +* [Linux Power Management](../tools/linux-power-management.md) — Systemd sleep configuration, kernel sleep states, NVIDIA GPU suspend/resume, diagnostic tools, kernel parameters, and automated testing procedures. +* [Niri](../tools/niri/index.md) — Scrollable-tiling Wayland compositor. Full keybind cheat sheet, configuration syntax, window management, workspace navigation, and action reference. + +### Pi Packages + +* [pi-browser-use](../packages/pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with `browser_` prefix, full config reference, session modes, vision model setup, and tool augmentation docs. +* [pi-permission-system](../packages/pi-permission-system.md) — 10 docs covering permission enforcement, config reference, session approvals, cross-extension API, subagent integration, troubleshooting, and migration guides. + +### Skills + +* [Npx Skills](../skills/npx-skills.md) — Distribution and installation patterns for agent skills via npm, package structure, SKILL.md frontmatter, discovery rules, and the Agent Skills specification. +* [Vercel Labs `skills` CLI](../skills/vercel-skills.md) — CLI meta-installer for cross-agent skill distribution, supporting 68+ agents, with add/use/find/list/update/remove commands. + +### References + +* [OKF v0.1 Specification](../references/okf-spec.md) — Complete specification for OKF knowledge bundles: bundle structure, frontmatter fields, concept documents, index/log files, cross-linking, and conformance rules. +* [OKF Bundle Maintenance](../references/okf-maintenance.md) — Bundle maintenance: log.md format, frontmatter discipline, one-concept-per-file, staleness detection, and automation strategies. + +--- + +## Adding New Tool Documentation + +When a subagent fetches documentation for a new tool: + +1. Save it to `tools/<tool-name>/index.md` (multi-file) or `tools/<tool-name>.md` (small, single-concept). +2. Add an entry to this index table. +3. Include a brief description of what the document covers. +4. Add YAML frontmatter with `type` and `description`. +5. Update `log.md` with the change. + +--- + +## Index Format + +Give each row this content: + +- **Tool** — the tool or technology name +- **File / Path** — relative path within this directory +- **Status** — for example, "Complete", "Partial", "Needs Update" diff --git a/omp-docs/core/index.md b/omp-docs/core/index.md new file mode 100644 index 0000000..4748631 --- /dev/null +++ b/omp-docs/core/index.md @@ -0,0 +1,13 @@ +# Core Documentation + +These files define the structural conventions that govern the pi agent system itself. They are the grammar rules — boring until you break them, then devastating. + +## Concept Files + +* [AGENTS.md Format Specification](agents-md-format.md) — Canonical structure and conventions for the system-level instruction file that governs agent behavior. +* [AGENTS.md Index](index-doc.md) — Overview of the cached tool documentation system and how to add new entries. +* [Pi Settings System](settings.md) — Current system configuration: providers, models, packages, subagent overrides, and runtime options. + +## Change Tracking + +* [Bundle Change Log](log.md) — Chronological update history. diff --git a/omp-docs/core/log.md b/omp-docs/core/log.md new file mode 100644 index 0000000..f0509ab --- /dev/null +++ b/omp-docs/core/log.md @@ -0,0 +1,21 @@ +--- +type: changelog +title: Core Bundle Change Log +description: Change log for the core documentation directory — tracks migrations and structural changes. +tags: + - core + - changelog + - okf +timestamp: 2026-07-18 +--- + +# Core Bundle Change Log + +## 2026-07-18 +- **Migration**: Converted `index.md` (root) to `core/index-doc.md` — moved root bundle index into core domain +- **Migration**: Converted `agents-md-format.md` (root) to `core/agents-md-format.md` — agents-md format belongs in core +- **Creation**: Established `core/` directory with `index.md` as the domain entry point +- **Creation**: This change log for tracking core directory modifications + +## 2026-07-15 +- **Initialization**: OKF v0.1 conversion of the entire docs bundle — frontmatter applied, structure established, first `log.md` entries created diff --git a/omp-docs/core/settings.md b/omp-docs/core/settings.md new file mode 100644 index 0000000..ceaba6f --- /dev/null +++ b/omp-docs/core/settings.md @@ -0,0 +1,240 @@ +--- +type: reference +title: Pi Settings System (settings.json) +description: Complete reference for pi's main configuration file — providers, models, packages, subagent overrides, and runtime options. +tags: + - settings + - configuration + - json + - providers + - models + - subagents +verified: 2026-08-28 +timestamp: 2026-08-28 +--- + +# pi Settings System (`settings.json`) + +`settings.json` is pi's main configuration file. It determines which models the agent talks to, which packages load, how subagents behave, and general runtime preferences. + +**Location:** `/home/dank/.pi/agent/settings.json` + +**Format:** JSON. + +--- + +## Current Configuration + +```json +{ + "lastChangelogVersion": "0.84.3", + "theme": "dark", + "defaultProvider": "llamacpp (dankclaw)", + "defaultModel": "frank-default-large", + "defaultThinkingLevel": "medium", + "hideThinkingBlock": false, + "subagents": { + "defaultModel": "frank-default-small", + "defaultThinking": "max", + "agentOverrides": { + "scout": { "model": "frank-default-small" }, + "researcher": { "model": "frank-default-small" }, + "planner": { "model": "frank-default-large" }, + "worker": { "model": "frank-default-large" }, + "reviewer": { "model": "frank-default-large" }, + "oracle": { "model": "frank-default-large" }, + "context-builder": { "model": "frank-default-large" } + }, + "watchdog": { "enabled": true } + }, + "packages": [ + "npm:@wierdbytes/pi-peon", + "npm:pi-web-access", + "npm:@narumitw/pi-worktree", + "npm:@juicesharp/rpiv-todo", + "npm:@juicesharp/rpiv-ask-user-question", + "npm:@ff-labs/pi-fff", + "npm:pi-intercom", + "npm:@juicesharp/rpiv-btw", + "npm:@xynogen/pix-pretty", + "npm:@xynogen/pix-bash", + "npm:@xynogen/pix-ssh", + "npm:@xynogen/pix-write", + "npm:@xynogen/pix-sudo", + "npm:@xynogen/pix-read", + "npm:@xynogen/pix-ls", + "npm:@xynogen/pix-edit" + ], + "enableSkillCommands": true, + "autocompleteMaxVisible": 10, + "terminal": { "showTerminalProgress": true }, + "steeringMode": "one-at-a-time", + "transport": "auto", + "httpIdleTimeoutMs": 0, + "retry": { + "enabled": true, + "maxRetries": 3, + "baseDelayMs": 10000 + }, + "markdown": { "mermaid": "streaming" }, + "fullscreenScrollbar": "always", + "tuiMode": "fullscreen", + "warnings": { "anthropicExtraUsage": false }, + "treeFilterMode": "default", + "doubleEscapeAction": "none", + "enabledModels": [ + "llamacpp (dankserver)/frank-default-small", + "llamacpp (dankclaw)/frank-default-large", + "openrouter/~deepseek/deepseek-v4-flash-latest", + "openrouter/openai/gpt-5.6-luna" + ], + "outputPad": 1, + "editorPaddingX": 0, + "modelThinkingLevels": { + "llamacpp (dankclaw)/frank-default-large": "medium", + "llamacpp (dankserver)/frank-default-small": "medium" + } +} +``` + +--- + +## Top-Level Fields + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `lastChangelogVersion` | string | No | Schema version. Incremented on schema changes. Mismatch triggers a migration prompt. | +| `theme` | string | No | UI theme. Values: `"dark"`, `"light"`. | +| `defaultProvider` | string | **Yes** | Provider name from `models.json`. Pi will not start without a valid provider. | +| `defaultModel` | string | **Yes** | Model ID within the default provider. Must match an `id` in `models.json`. | +| `defaultThinkingLevel` | string | No | Default reasoning depth: `"off"`, `"low"`, `"medium"`, `"high"`, `"max"`. | +| `hideThinkingBlock` | boolean | No | If `true`, the agent's chain-of-thought is hidden in the TUI. | +| `packages` | string[] | No | Installed pi packages. Format: `npm:<package-name>`. | +| `subagents` | object | No | Subagent configuration. Controls model selection per agent role. | +| `enableSkillCommands` | boolean | No | Enable skill command triggers. | +| `autocompleteMaxVisible` | number | No | Max visible autocomplete suggestions. | +| `terminal` | object | No | Terminal display options. | +| `steeringMode` | string | No | Agent steering mode (e.g. `"one-at-a-time"`). | +| `transport` | string | No | Transport protocol (`"auto"`, etc.). | +| `httpIdleTimeoutMs` | number | No | HTTP idle timeout in milliseconds. | +| `retry` | object | No | Retry configuration with backoff. | +| `markdown` | object | No | Markdown rendering options (e.g. mermaid mode). | +| `fullscreenScrollbar` | string | No | Scrollbar visibility mode. | +| `tuiMode` | string | No | TUI display mode. | +| `warnings` | object | No | Warning suppression settings. | +| `treeFilterMode` | string | No | File tree filtering mode. | +| `doubleEscapeAction` | string | No | Double-escape key action. | +| `enabledModels` | string[] | No | List of all available model IDs for switching. | +| `outputPad` | number | No | Output padding. | +| `editorPaddingX` | number | No | Editor X padding. | +| `modelThinkingLevels` | object | No | Per-model thinking level overrides. | + +--- + +## Subagent Configuration + +The `subagents` block controls which models subagents use and how they reason. + +### Fields + +| Field | Type | Description | +|-------|------|-------------| +| `defaultModel` | string | Fallback model for subagents without an explicit override. | +| `defaultThinking` | string | Default reasoning depth for subagents. | +| `agentOverrides` | object | Per-role model assignments. Keys are agent roles. | +| `watchdog.enabled` | boolean | Enable the watchdog system that monitors subagent health. | + +### Agent Roles and Model Assignments + +| Role | Model | Purpose | +|------|-------|---------| +| `scout` | `frank-default-small` | Quick exploration tasks | +| `researcher` | `frank-default-small` | Web research and information gathering | +| `planner` | `frank-default-large` | Task planning and decomposition | +| `worker` | `frank-default-large` | Heavy implementation work | +| `reviewer` | `frank-default-large` | Code and document review | +| `oracle` | `frank-default-large` | Complex reasoning and analysis | +| `context-builder` | `frank-default-large` | Building context for other agents | + +--- + +## Retry + +Automatic agent-level retries use exponential backoff. The current configuration allows three retries with delays of **10 seconds, 20 seconds, and 40 seconds**. + +```json +{ + "retry": { + "enabled": true, + "maxRetries": 3, + "baseDelayMs": 10000 + } +} +``` + +--- + +## Provider Configuration + +**Location:** `~/.pi/agent/models.json` + +Providers define where pi gets its LLM. The default provider is specified in `settings.json` and the provider definitions live in `models.json`. + +Currently configured providers: + +| Provider | Base URL | Model | GPU | +|----------|----------|-------|-----| +| `llamacpp (dankserver)` | `http://192.168.0.235:7770/v1` | `frank-default-small` (Qwen3.6-35B-A3B FP8, moe-cache 2048) | RTX 3090 | +| `llamacpp (dankclaw)` | `http://192.168.0.143:7770/v1` | `frank-default-large` (Qwen3.8-Flash-Next Q4_0 ROCmFP4 Strix) | RTX 4070 Max-Q | + +See [[models|models]] for the complete `models.json` reference. + +--- + +## Package Configuration + +**Location:** `~/.pi/agent/settings.json` (via `packages` array) + `~/.pi/agent/npm/` (on-disk) + +Each package entry is a specifier string. The format is `npm:<package-name>`. When pi starts, it: + +1. Reads the `packages` array from `settings.json` +2. Checks `~/.pi/agent/npm/node_modules/<name>/` for each package +3. Loads extensions, skills, prompts, and themes from each package + +Currently installed: + +| Package | Version | Description | +|---------|---------|-------------| +| `@wierdbytes/pi-peon` | 0.1.1 | CESP/OpenPeon sound-pack player for pi lifecycle events | +| `pi-web-access` | 0.22.0 | Web search, URL fetching, GitHub cloning, PDF extraction, YouTube understanding | +| `@narumitw/pi-worktree` | 0.51.6 | Worktree management for git-based parallel development | +| `@juicesharp/rpiv-todo` | 2.7.1 | Todo/task management package | +| `@juicesharp/rpiv-ask-user-question` | 2.7.1 | Interactive user question prompts | +| `@ff-labs/pi-fff` | 0.10.5 | File/flow functions | +| `pi-intercom` | 0.12.0 | Inter-process communication | +| `@juicesharp/rpiv-btw` | 2.7.1 | Between-task utilities | +| `@xynogen/pix-pretty` | 1.18.1 | Code formatting | +| `@xynogen/pix-bash` | 0.2.1 | Bash shell utilities | +| `@xynogen/pix-ssh` | 0.2.6 | SSH management | +| `@xynogen/pix-write` | 0.2.1 | File writing utilities | +| `@xynogen/pix-sudo` | 0.3.20 | Privileged operations | +| `@xynogen/pix-read` | 0.2.1 | File reading utilities | +| `@xynogen/pix-ls` | 0.2.1 | Directory listing | +| `@xynogen/pix-edit` | 0.2.1 | File editing utilities | + +See [packages](../packages/index.md) for full package documentation. + +--- + +## Migration + +When `lastChangelogVersion` is behind pi's internal version, pi prompts for migration. The migration updates the JSON structure while preserving values. Back up before migrating. + +--- + +## See Also + +- [pi](../pi/index.md) — Pi configuration overview +- [[models|models]] — Provider and model definitions +- [packages](../packages/index.md) — Installed package documentation +- [[skills|skills]] — Installed skill documentation diff --git a/omp-docs/engineering/agents-files.md b/omp-docs/engineering/agents-files.md new file mode 100644 index 0000000..6182549 --- /dev/null +++ b/omp-docs/engineering/agents-files.md @@ -0,0 +1,100 @@ +--- +type: reference +title: Agent Instruction Files and Agent Skills +description: Best practices for AGENTS.md, CLAUDE.md, SYSTEM.md, and the Agent Skills SKILL.md standard. +tags: + - agents-md + - claude-md + - system-md + - agent-skills + - unverified +timestamp: 2026-08-11 +--- +verified: 2026-08-28 + +# Agent Instruction Files and Agent Skills + +This page explains the files that control how an AI coding agent works in a project. Use it when you create or review agent behavior configuration. + +## AGENTS.md + +`AGENTS.md` is the open, cross-tool format for coding-agent instructions. The Agentic AI Foundation (under the Linux Foundation) stewards it. Over 20 coding agents support it, including Cursor, Codex, and Claude Code. + +The format is plain Markdown. It has no required fields. Any heading structure works. Agents read the nearest `AGENTS.md` in the directory tree. In a monorepo, the agent uses a nested `AGENTS.md` per package. + +Include these sections in an `AGENTS.md`: + +* Project overview. +* Setup and build commands. +* Code style guidelines. +* Testing instructions. +* Pull request instructions. +* Security considerations. +* Deployment steps. +* Commit message conventions. + +Agents load content progressively. Put a short summary at the top. Put detailed instructions in later sections. + +## CLAUDE.md + +`CLAUDE.md` is Anthropic's tool-specific instruction file. Claude Code reads `CLAUDE.md` by default, not `AGENTS.md`. Files load in this order: + +1. Managed policy (`/etc/claude-code/CLAUDE.md`). +2. User scope (`~/.claude/CLAUDE.md`). +3. Project scope (`./CLAUDE.md`). +4. Local scope (`./CLAUDE.local.md`). + +Keep each file under 200 lines. Use the `@path/to/file` syntax to import other files. Use path-scoped rules in `.claude/rules/*.md` with `paths` frontmatter for directory-specific rules. + +To make a repository work in both AGENTS.md and CLAUDE.md workflows, create a `CLAUDE.md` that imports `AGENTS.md` with the `@AGENTS.md` syntax, or use a symlink. + +## SYSTEM.md + +`SYSTEM.md` sets the system-level role and behavior for an agent. It establishes the persona, the prime directive, and the binding rules. In this setup, `/home/dank/.pi/agent/SYSTEM.md` defines the Comrade Chief Designer persona and the ASD-STE100 voice rules. + +Use `SYSTEM.md` for stable, cross-project rules. Use `AGENTS.md` for project-specific context. Do not duplicate content between them. Keep the division of labor clear. + +## Agent Skills Standard + +An agent skill is a directory that contains a `SKILL.md` file. Skills extend an agent's capabilities. The open standard lives at [agentskills.io](https://agentskills.io). Over 50 agents support it. + +The `SKILL.md` frontmatter includes these fields: + +```yaml +--- +name: my-skill +description: What this skill does +license: MIT +compatibility: node>=18 +metadata: + internal: false +--- +``` + +The `name` field is required and must use lowercase alphanumeric plus hyphens. The `description` field is required. Keep the name under 64 characters. Keep the description under 1024 characters. + +Skills use progressive disclosure in three stages: + +* Discovery: the agent loads only the name and description at startup. +* Activation: the agent reads the full `SKILL.md` when a task matches. +* Execution: the agent follows the instructions and reads resources on demand. + +This keeps the context footprint small. + +## Distribution + +Distribute skills through npm packages with a `pi` manifest, or through the `skills` CLI from Vercel Labs. See the [Skills Documentation](../skills/index.md) pages for details. + +## Citations + +* [agents.md](https://agents.md/) +* [OpenAI Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/) (unverified — returned 403) +* [Claude Code memory documentation](https://code.claude.com/docs/en/memory) +* [Agent Skills standard](https://agentskills.io/) +* [agentskills/agentskills](https://github.com/agentskills/agentskills) +* [vercel-labs/skills](https://github.com/vercel-labs/skills) + +## See Also + +* [SDLC and Tooling](sdlc.md) +* [Skills Ecosystem](skills-ecosystem.md) diff --git a/omp-docs/engineering/index.md b/omp-docs/engineering/index.md new file mode 100644 index 0000000..f8cc1a2 --- /dev/null +++ b/omp-docs/engineering/index.md @@ -0,0 +1,26 @@ +# Software Engineering Best Practices + +Current (2025/2026) best practices for software projects, grouped by lifecycle and ecosystem. + +This area distills grounded research into an OKF knowledge bundle. Each page covers one domain. Cross-links connect related pages. + +## Topics + +* [SDLC and Tooling](sdlc.md) - Git branching, CI/CD, testing, code review, versioning, dev environments. +* [Agent Instruction Files](agents-files.md) - AGENTS.md, CLAUDE.md, SYSTEM.md, and the Agent Skills standard. +* [Language and Framework Stacks](languages/index.md) - Node/JavaScript, React, Python, Rust, Go. +* [Infrastructure and Cloud](infra/index.md) - Terraform/OpenTofu, containers, Kubernetes, AWS, DigitalOcean, Hetzner. +* [Pi Plugins](plugins.md) - The pi extension ecosystem and notable packages. +* [Skills Ecosystem](skills-ecosystem.md) - skills.sh registry and the top skills. +* [Signal Remote Control](signal-remote.md) - Drive a pi instance from Signal messages. + +## Conventions + +Sources appear in each page under `# Citations`. Timestamps use ISO 8601. The bundle follows the [OKF v0.1 specification](../references/okf-spec.md). + +## See Also + +* [Research](../research/index.md) - Hardware-specific research. +* [Agentic Web Research](../agentic-web-research/index.md) - Self-hosted web research infrastructure. +* [Pi Configuration](../pi/index.md) - The local pi agent setup. +* [Skills Documentation](../skills/index.md) - Skill distribution and installation patterns. diff --git a/omp-docs/engineering/infra/cloud.md b/omp-docs/engineering/infra/cloud.md new file mode 100644 index 0000000..b533de5 --- /dev/null +++ b/omp-docs/engineering/infra/cloud.md @@ -0,0 +1,80 @@ +--- +type: reference +title: Cloud Providers - AWS, DigitalOcean, Hetzner +description: Current best practices for AWS, DigitalOcean, and Hetzner - bootstrapping, IaC, cost, and lifecycle. +tags: + - aws + - digitalocean + - hetzner + - cloud + - infrastructure + - engineering +timestamp: 2026-08-11 +verified: 2026-08-28 +--- +# Cloud Providers + +This page compares current (2025/2026) practices for AWS, DigitalOcean, and Hetzner. + +## AWS + +Use infrastructure as code with Terraform or OpenTofu. Build a landing zone with AWS Control Tower or a `aws-landing-zone` module. + +Use these services as the baseline: + +* EC2 for compute. +* RDS for managed databases. +* EKS for managed Kubernetes. +* VPC for networking. +* S3 for object storage. +* IAM for access control. + +Optimize cost with Savings Plans, Spot instances for stateless work, and Reserved instances for databases. + +Set a security baseline with organization SCPs, GuardDuty, Security Hub, and KMS for encryption. + +## DigitalOcean + +Use Droplets for simple virtual servers. Use the App Platform as a PaaS for containerized applications. Use managed databases for PostgreSQL, MySQL, and Redis. + +Use `doctl` as the command-line tool. Use the Terraform provider for infrastructure as code. + +Droplets start around $4 per month. DigitalOcean costs more per compute unit than Hetzner but gives a better developer experience. + +## Hetzner + +Hetzner Cloud offers a strong cost advantage. Compute costs are roughly half or less than DigitalOcean and AWS. + +Use the `hcloud` CLI or the official `hashicorp/hcloud` Terraform provider. Manage servers, networks, firewalls, load balancers, and volumes. + +Hetzner has fewer regions. It has no managed Kubernetes service and no managed databases. Run k3s, k0s, or Talos for Kubernetes. + +Hetzner suits cost-sensitive homelabs, European workloads, and k3s or k0s clusters. + +## Provider Decision + +| Factor | AWS | DigitalOcean | Hetzner | +|--------|-----|--------------|---------| +| Cost | High | Medium | Low | +| Services | Enterprise | Managed databases | Limited | +| Regions | Many | Several | Few | +| Best for | Enterprise | Developer experience | Cost-sensitive clusters | + +## Related Tools + +* cloud-init for first-boot configuration. +* Ansible for configuration management. +* WireGuard or Tailscale for private networking. +* Cloudflare Tunnels to expose services without open ports. + +## Citations + +* [AWS documentation](https://docs.aws.amazon.com/) +* [DigitalOcean](https://www.digitalocean.com/) +* [Hetzner Cloud](https://www.hetzner.com/cloud/) +* [Terraform hcloud provider](https://registry.terraform.io/providers/hetznercloud/hcloud/latest/docs) + +## See Also + +* [Terraform and OpenTofu](terraform.md) +* [Kubernetes](kubernetes.md) diff --git a/omp-docs/engineering/infra/containers.md b/omp-docs/engineering/infra/containers.md new file mode 100644 index 0000000..8b9540e --- /dev/null +++ b/omp-docs/engineering/infra/containers.md @@ -0,0 +1,100 @@ +--- +type: reference +title: Docker and Podman +description: Current best practices for Docker and Podman - BuildKit, multi-stage builds, rootless operation, and pods. +tags: + - docker + - podman + - containers + - infrastructure + - engineering +timestamp: 2026-08-16 +verified: 2026-08-28 +--- +# Docker and Podman + +This page covers current (2025/2026) best practices for containers. + +## Docker + +Use BuildKit for builds. It enables incremental builds, cache mounts, and secret mounts. + +Use multi-stage builds for production images. Build in a full stage with the toolchain. Copy only the artifacts to a minimal final stage. Name each stage with `AS`. + +Harden images with these practices: + +* Use distroless or alpine base images. +* Set `USER` to a non-root user. +* Use `ENTRYPOINT` in exec form. +* Add a `HEALTHCHECK`. +* Pin base image digests. +* Use a `.dockerignore` file. + +Use Docker Compose v2 for multi-container applications. Run `docker compose` without a hyphen. + +## Podman + +Podman runs without a daemon and rootless by default. Run it as a non-root user. An alias `alias docker=podman` works for most commands. + +Use Podman pods to group containers that share network and IPC namespaces. Pods suit single-host service groups. + +Use Quadlet for container lifecycle management under systemd. `podman generate systemd` is deprecated as of Podman 5.7; the deprecation notice points to Quadlet. + +Podman is a good choice for Linux servers, homelabs, and CI runners. + +### Quadlet (systemd-managed containers) + +Quadlet files are systemd unit files with a podman section (`[Container]`, `[Network]`, etc.). Podman ships a systemd generator that turns them into `container` services. + +Rootless search path: `~/.config/containers/systemd/`. System-wide: `/etc/containers/systemd/`. + +| Fact | Value | +|------|-------| +| Unit naming (podman 5.x) | `foo.container` → `foo.service` (no `container-` prefix) | +| Container naming | `ContainerName=foo` or default `systemd-foo` | +| Boot start | `[Install] WantedBy=default.target` in the file; the generator applies it | +| Rootless boot start | enable user-level linger: `loginctl enable-linger <user>` | +| Start behavior | `podman run --name ... --replace --rm`; stop removes the container | +| Cross-container deps | `[Unit] Wants=` / `After=` referencing other quadlet unit names | +| Network | `Network=foo.network` uses a podman network created from `foo.network` | +| Long pulls | add `[Service] TimeoutStartSec=900` | + +Reference: `man podman-systemd.unit` (podman-systemd.unit(5)). + +#### Gotchas found in the field (2026-08-16, Gitea migration on dankclaw) + +- The automatic rootless default network (`podman`) has `dns_enabled: false`. Container names do not resolve on it. Create a quadlet `.network` file (DNS is enabled by default for quadlet networks) and point the containers at it. +- `${VAR}` expansion in the generated `ExecStart` needs the variable in the *systemd unit environment*. Put `EnvironmentFile=/path/to/env` in the `[Service]` section of the quadlet file. An `EnvironmentFile=` in `[Container]` only lands in the ignored `[X-Container]` section and does not feed expansion. +- A podman restart (or `systemctl --user daemon-reload`) re-runs the generator after quadlet file edits. Verify the parsed unit with `systemctl --user cat <unit>`. +- Bind-mounted files created by the container are owned by the mapped host UID (container uid 1000 → first subuid + 1000). Edit them with `podman exec --user 1000 <container> ...`. + +#### Gotchas found in the field (2026-08-19, SearXNG trio migration on dankclaw) + +- The quadlet generator rejects several compose-familiar keys in `[Container]` and **silently skips the whole unit** (the error is only in `journalctl --user`, and the unit simply never appears in `systemctl list-unit-files`). Use the podman-flag names: `AddCapability=` (not `CapAdd=`), `AddDevice=HOST:CONTAINER` (not `Device=` — that is a `[Volume]` key). When a unit mysteriously does not generate, read the journal for `quadlet-generator: converting "...": unsupported key`. +- Quadlet units are **generated** units (they live in `/run/user/UID/systemd/generator/`). `systemctl enable <unit>` fails on them with "transient or generated". You do not enable them: the `[Install] WantedBy=default.target` in the `.container` file *is* the enablement — `systemctl is-enabled` reports `generated`. With user linger on, they start at boot. Just `daemon-reload` then `start`. +- A `.network` unit is also generated and cannot be enabled. It is pulled in automatically by any container that sets `Wants=`/`After=` on it (or `Network=<name>.network`). +- To make one container reuse another's network namespace (the compose `network_mode: service:X` equivalent), set `Network=<name>.container` on the consumer. The generator adds the dependency on `<name>.service`. This is how SearXNG exits the Gluetun WireGuard tunnel: `Network=gluetun.container`. +- Pin a quadlet network CIDR with `Subnet=<cidr>` in the `.network` file (maps to `podman network create --subnet`). Rootless podman otherwise reassigns the CIDR, which breaks any `trusted_proxies` entry that references it. +- A working pattern for a boot-persistent trio: a `.network` (DNS on, `Subnet=` pinned) that the VPN client and the cache join, plus the consumer container on `Network=<vpn>.container`. Secrets live in a mode-0600 env file referenced by `EnvironmentFile=` in each unit's `[Service]`. + +## Docker vs Podman + +| Factor | Docker | Podman | +|--------|--------|--------| +| Platform | Mac and Windows | Linux focus | +| Model | Daemon-based | Rootless and daemonless | +| Default user | Root | Non-root | +| Grouping | Compose services | Pods | + +Use Docker for cross-platform development. Use Podman rootless for Linux servers and security-conscious deployments. + +## Citations + +* [Docker documentation](https://docs.docker.com/) +* [Podman documentation](https://podman.io/docs) +* [Container Specification](https://containers.dev/) + +## See Also + +* [Kubernetes](kubernetes.md) +* [Go](../languages/go.md) diff --git a/omp-docs/engineering/infra/index.md b/omp-docs/engineering/infra/index.md new file mode 100644 index 0000000..be7a44a --- /dev/null +++ b/omp-docs/engineering/infra/index.md @@ -0,0 +1,15 @@ +# Infrastructure and Cloud + +Current (2025/2026) best practices for infrastructure as code, containers, orchestration, and cloud providers. + +## Topics + +* [Terraform and OpenTofu](terraform.md) - IaC modules, state, backends, and orchestration. +* [Docker and Podman](containers.md) - BuildKit, multi-stage builds, rootless, and pods. +* [Kubernetes](kubernetes.md) - Helm, k3s, k0s, and Talos. +* [Cloud Providers](cloud.md) - AWS, DigitalOcean, and Hetzner. + +## See Also + +* [Engineering](../index.md) - The parent area. +* [SDLC and Tooling](../sdlc.md) diff --git a/omp-docs/engineering/infra/kubernetes.md b/omp-docs/engineering/infra/kubernetes.md new file mode 100644 index 0000000..af23047 --- /dev/null +++ b/omp-docs/engineering/infra/kubernetes.md @@ -0,0 +1,80 @@ +--- +type: reference +title: Kubernetes +description: Current best practices for Kubernetes - Helm charts, k3s, k0s, and Talos Linux. +tags: + - kubernetes + - helm + - k3s + - k0s + - talos + - infrastructure + - engineering +timestamp: 2026-08-11 +verified: 2026-08-28 +--- +# Kubernetes + +This page covers current (2025/2026) best practices for Kubernetes. + +## Helm + +Use Helm to manage charts. Follow the canonical chart layout: + +``` +my-chart/ +├── Chart.yaml +├── values.yaml +├── values.schema.json +├── charts/ +├── templates/ +│ ├── deployment.yaml +│ ├── service.yaml +│ └── _helpers.tpl +├── .helmignore +└── NOTES.txt +``` + +Use `_helpers.tpl` for consistent labels, such as `app.kubernetes.io/*`. Separate `values.yaml` per environment. Pin chart versions in CI. Run `helm lint` before packaging. + +Set `securityContext` to non-root and read-only root filesystem. Set resource requests and limits. + +## Distribution Choices + +| Tool | Best For | Notes | +|------|----------|-------| +| k3s | Fast bootstrap | Single binary, embedded addons, quick setup. | +| k0s | Vanilla Kubernetes | No host dependencies, `k0sctl` lifecycle tool. | +| Talos Linux | Secure immutable clusters | Small footprint, API-driven config. | + +### k3s + +Install with: + +```bash +curl -sfL https://get.k3s.io | sh - +``` + +k3s is a single binary under 100 MB. It is ready in about 30 seconds. Use SQLite for single-node or embedded etcd for high availability. + +### Talos Linux + +Talos is an immutable Kubernetes OS. It has no SSH, no shell, and no package manager. Configure it with declarative YAML through the `talosctl` gRPC API. Use automatic A/B upgrades with rollback. + +## Related Tools + +* Cilium or Calico for networking. +* ArgoCD or Flux for GitOps deployment. +* k0sctl for cluster lifecycle. + +## Citations + +* [Helm](https://helm.sh/) +* [k3s](https://k3s.io/) +* [k0s](https://k0sproject.io/) +* [Talos Linux](https://www.talos.dev/) + +## See Also + +* [Docker and Podman](containers.md) +* [Cloud Providers](cloud.md) diff --git a/omp-docs/engineering/infra/terraform.md b/omp-docs/engineering/infra/terraform.md new file mode 100644 index 0000000..04c25d9 --- /dev/null +++ b/omp-docs/engineering/infra/terraform.md @@ -0,0 +1,79 @@ +--- +type: reference +title: Terraform and OpenTofu +description: Current best practices for Terraform and OpenTofu - module structure, state management, backends, and orchestration. +tags: + - terraform + - opentofu + - iac + - infrastructure + - engineering +timestamp: 2026-08-11 +verified: 2026-08-28 +--- +# Terraform and OpenTofu + +This page covers current (2025/2026) best practices for Terraform and OpenTofu. + +## OpenTofu vs Terraform + +OpenTofu is the open-source fork of Terraform. It uses the MPL 2.0 license. Terraform moved to the Business Source License. Both remain compatible with the same configurations and most providers. + +Use OpenTofu when license portability matters. Use Terraform when you need HashiCorp's commercial extensions. + +## Module Structure + +Separate infrastructure into layers: + +``` +infrastructure/ +├── modules/ # Reusable building blocks +└── environments/ + ├── dev/ + ├── stage/ + └── prod/ +``` + +Environment modules call the reusable modules. Root modules declare providers and the backend. + +## State Management + +Never commit `.tfstate` to version control. Use a remote backend only. + +The AWS remote backend uses S3 and DynamoDB: + +* `bucket` for the state bucket. +* `key` for the state file path. +* `dynamodb_table` for state locking. +* `encrypt` for encryption at rest. + +Enable versioning and server-side encryption on the state bucket. + +Use separate state files per environment. Do not use workspaces for separate environments. + +## Security and Lifecycle + +* Mark sensitive values with `sensitive = true`. +* Pin provider versions with `required_providers`. +* Run `terraform import` to adopt existing infrastructure. +* Run `terraform plan` periodically to detect drift. +* Use lifecycle blocks for resource replacement policies. + +## Related Tools + +* Terragrunt for orchestration: DRY config, hooks, and run queues. +* Pulumi for infrastructure as code in real programming languages. +* Packer for building machine images. +* Atlantis for pull request based Terraform CI/CD. + +## Citations + +* [Terraform documentation](https://developer.hashicorp.com/terraform) +* [OpenTofu](https://opentofu.org/) +* [Terragrunt](https://terragrunt.com/) +* [AWS backend](https://developer.hashicorp.com/terraform/language/settings/backends/s3) + +## See Also + +* [Cloud Providers](cloud.md) +* [Kubernetes](kubernetes.md) diff --git a/omp-docs/engineering/languages/go.md b/omp-docs/engineering/languages/go.md new file mode 100644 index 0000000..5ac2d22 --- /dev/null +++ b/omp-docs/engineering/languages/go.md @@ -0,0 +1,93 @@ +--- +type: reference +title: Go +description: Current best practices for Go projects - modules, project layout, HTTP frameworks, and tooling. +tags: + - go + - golang + - bootstrap + - engineering +timestamp: 2026-08-11 +verified: 2026-08-28 +--- + +CUT +# Go + +This page covers current (2025/2026) best practices for Go projects. + +## Bootstrap + +Initialize a module: + +```bash +go mod init my-module +``` + +Then write a `main.go` with `package main`. + +## Project Layout + +Follow the Standard Go Project Layout: + +``` +my-project/ +├── cmd/ # Application entrypoints +├── internal/ # Private application code +├── pkg/ # Public library code +├── api/ # Protobuf or OpenAPI definitions +├── deploy/ # Dockerfiles and Helm charts +├── scripts/ # Build and CI scripts +├── go.mod +└── go.sum +``` + +Use `internal/` for code that must stay private to the module. + +## Tooling + +| Category | Tool | Notes | +|----------|------|-------| +| Module manager | go modules | Built into the toolchain. | +| Formatter | gofmt | Built in. | +| Linter | golangci-lint | The standard CI aggregator. | +| Testing | `go test ./...` | Use table-driven tests. | +| Static analysis | staticcheck | Use with golangci-lint. | + +## HTTP Frameworks + +| Framework | Best For | Notes | +|-----------|----------|-------| +| Standard `net/http` | Most Go projects | Idiomatic, no dependencies. | +| chi v5 | REST APIs | Minimalist, stdlib-compatible. | +| gin | High-throughput APIs | Fast, JSON binding. | +| echo | Full-featured APIs | Middleware and validation. | + +Use the standard library or chi for most projects. + +## Notable 2025/2026 Changes + +* Go 1.24 added generic type aliases and `tool` directives in `go.mod`. +* `go run` and `go build` cache executables and embed VCS metadata. +* `go test -json` gives structured output for CI. + +## Related Technologies + +* pgx for PostgreSQL. +* slog for structured logging. +* cobra for command-line interfaces. +* gRPC with `google.golang.org/grpc`. +* testcontainers-go for integration tests. + +## Citations + +* [Go modules](https://go.dev/doc/modules) +* [Go 1.24 release notes](https://go.dev/doc/go1.24) +* [Standard Go Project Layout](https://github.com/golang-standards/project-layout) +* [chi](https://github.com/go-chi/chi) + +## See Also + +* [SDLC and Tooling](../sdlc.md) +* [Rust](rust.md) +* [Docker and Podman](../infra/containers.md) diff --git a/omp-docs/engineering/languages/index.md b/omp-docs/engineering/languages/index.md new file mode 100644 index 0000000..5f6ed1c --- /dev/null +++ b/omp-docs/engineering/languages/index.md @@ -0,0 +1,22 @@ +# Language and Framework Stacks + +Current (2025/2026) bootstrap, tooling, and best practices for the major language ecosystems. + +Each page covers one ecosystem. Use the page that matches the project language. + +## Topics + +* [Node.js and JavaScript](node-js.md) - Runtimes, package managers, TypeScript, tooling, monorepos. +* [React](react.md) - Vite vs Next.js, component patterns, testing. +* [Python](python.md) - uv, pyproject.toml, frameworks, linting, testing. +* [Rust](rust.md) - cargo, editions, web frameworks, tooling. +* [Go](go.md) - modules, project layout, HTTP frameworks, tooling. + +## Cross-Ecosystem Patterns + +* [SDLC and Tooling](../sdlc.md) - Git, CI/CD, testing, environments. +* [Infrastructure and Cloud](../infra/index.md) - Containers and deployment. + +## See Also + +* [Engineering](../index.md) - The parent area. diff --git a/omp-docs/engineering/languages/node-js.md b/omp-docs/engineering/languages/node-js.md new file mode 100644 index 0000000..d283372 --- /dev/null +++ b/omp-docs/engineering/languages/node-js.md @@ -0,0 +1,87 @@ +--- +type: reference +title: Node.js and JavaScript +description: Current bootstrap, tooling, and framework best practices for Node.js and JavaScript projects. +tags: + - node + - javascript + - typescript + - bootstrap + - engineering +timestamp: 2026-08-11 +verified: 2026-08-28 +--- + +CUT +# Node.js and JavaScript + +This page covers current (2025/2026) best practices for Node.js and JavaScript projects. + +## Runtime and Package Manager + +Use Node.js 22 LTS or Node.js 24 LTS. Use these versions for stability in production. + +Choose a package manager by project type: + +* npm for the default. +* pnpm for monorepos. +* Bun as an all-in-one runtime, package manager, test runner, and bundler. + +## TypeScript + +TypeScript is the default for new projects. Configure `strict: true` in `tsconfig.json`. Target `ES2022` or later. Use `module: ESNext` and `moduleResolution: bundler`. + +## Bootstrap + +Scaffold a Vite project with: + +```bash +npm create vite@latest my-app -- --template react-ts +``` + +Scaffold a full-stack SSR app with Next.js: + +```bash +npx create-next-app@latest my-app --yes +``` + +## Tooling + +| Category | Tool | Notes | +|----------|------|-------| +| Linter | ESLint 9 with flat config | Use `eslint.config.mjs`. | +| Formatter | Prettier or Biome | Biome is faster and Prettier-compatible. | +| Testing | Vitest or Jest | Vitest is the default for Vite projects. | +| Bundler | Vite or Turbopack | Turbopack is the Next.js default. | + +Use Biome if you want one fast tool for lint and format. Biome gained many lint rules from ESLint and TypeScript ESLint. + +## Frameworks + +* Express and Fastify for minimal servers. +* NestJS for structured, opinionated applications. +* Next.js for full-stack React with server-side rendering. + +## Monorepos + +Use Turborepo or Nx for JavaScript and TypeScript monorepos. Combine these tools with pnpm workspaces for dependency management. + +## Related Technologies + +* Remix, Nuxt, Astro, and SvelteKit as other meta-frameworks. +* Deno as an alternative runtime. +* esm.sh as a CDN for npm packages as ES modules. + +## Citations + +* [Node.js releases](https://nodejs.org/en/about/releases) +* [Vite](https://vite.dev/) +* [Biome](https://biomejs.dev/) +* [Vitest](https://vitest.dev/) +* [Bun](https://bun.com/) +* [Next.js documentation](https://nextjs.org/docs) + +## See Also + +* [React](react.md) +* [SDLC and Tooling](../sdlc.md) diff --git a/omp-docs/engineering/languages/python.md b/omp-docs/engineering/languages/python.md new file mode 100644 index 0000000..45669ab --- /dev/null +++ b/omp-docs/engineering/languages/python.md @@ -0,0 +1,79 @@ +--- +type: reference +title: Python +description: Current best practices for Python projects - uv, pyproject.toml, frameworks, linting, and testing. +tags: + - python + - uv + - fastapi + - django + - bootstrap + - engineering +timestamp: 2026-08-11 +verified: 2026-08-28 +--- + +CUT +# Python + +This page covers current (2025/2026) best practices for Python projects. + +## Package and Project Management + +Use `uv` for new projects. `uv` replaces pip, pip-tools, pyenv, poetry, and virtualenv. It is much faster than pip and supports workspaces and lockfiles. + +Scaffold a project with: + +```bash +uv init my-project --bare +``` + +The command creates a `pyproject.toml` and a virtual environment. A `uv.lock` file pins exact dependency versions. Do not edit the lockfile by hand. + +Use `pyproject.toml` as the project manifest. It follows PEP 621. This replaces the older `setup.py`. + +## Tooling + +| Category | Tool | Notes | +|----------|------|-------| +| Linter and formatter | Ruff | Replaces Black, isort, flake8, and pylint. | +| Type checker | pyright or mypy | Use pyright in VS Code. Use mypy for strict CI. | +| Testing | pytest | Use pytest-asyncio for async tests. | +| Pre-commit | pre-commit | Run ruff, mypy, and pytest. | + +## Framework Comparison + +| Framework | Best For | Notes | +|-----------|----------|-------| +| FastAPI | Modern REST APIs, async | Auto documentation, type-hint validation. | +| Django | Full-stack web apps | Batteries included: ORM, admin, auth. | +| Flask | Lightweight apps | Simpler than FastAPI. | + +Use FastAPI for new REST APIs. The recommended workflow is `uv run fastapi dev`. + +## Notable 2025/2026 Changes + +* `uv` is the dominant project manager. +* `ruff` replaced most separate lint and format tools. +* `pyproject.toml` is the universal manifest. +* Python 3.12 gives stability. Python 3.13 adds performance improvements. + +## Related Technologies + +* Uvicorn as the ASGI server. +* SQLAlchemy 2.0 with Alembic for the ORM and migrations. +* httpx for async HTTP clients. +* pydantic-settings for configuration. +* OpenTelemetry for observability. + +## Citations + +* [uv documentation](https://docs.astral.sh/uv/) +* [Ruff](https://ruff.rs/) +* [FastAPI](https://fastapi.tiangolo.com/) +* [pyproject-build](https://pyproject-build.github.io/) + +## See Also + +* [SDLC and Tooling](../sdlc.md) +* [Infrastructure and Cloud](../infra/index.md) diff --git a/omp-docs/engineering/languages/react.md b/omp-docs/engineering/languages/react.md new file mode 100644 index 0000000..45019d7 --- /dev/null +++ b/omp-docs/engineering/languages/react.md @@ -0,0 +1,82 @@ +--- +type: reference +title: React +description: Current best practices for React - Vite vs Next.js, component patterns, and testing. +tags: + - react + - nextjs + - frontend + - bootstrap + - engineering +timestamp: 2026-08-11 +verified: 2026-08-28 +--- + +CUT +# React + +This page covers current (2025/2026) best practices for React projects. + +## Framework Choice + +Create React App is deprecated. Use Vite or Next.js for new projects. + +* Use Vite + React for a single-page application with a separate API. +* Use Next.js for a full-stack application with server-side rendering. + +Next.js uses the App Router with React Server Components by default. Components render on the server unless you mark them with `"use client"`. + +## Bootstrap + +Scaffold a Vite project: + +```bash +npm create vite@latest my-app -- --template react-ts +``` + +Scaffold a Next.js project: + +```bash +npx create-next-app@latest my-app --yes +``` + +## Tooling + +| Category | Tool | Notes | +|----------|------|-------| +| CSS | Tailwind CSS | Default in create-next-app. | +| State | Zustand and TanStack Query | Zustand for client state. TanStack Query for server state. | +| Testing | Vitest and Testing Library | Unit and integration tests. | +| End-to-end | Playwright or Cypress | For user journeys. | +| Lint and format | Biome or ESLint | Use Biome for one fast tool. | + +## Component Patterns + +* Keep components, hooks, and types near the routes that use them. +* Use route groups for organization without changing the URL. +* Use `_components` for code that must not become a route. +* Use React Server Components to reduce client-side state. + +## Notable 2025/2026 Changes + +* React 19 is stable with Actions and new hooks. +* Next.js 16 uses Turbopack as the default bundler. +* Next.js no longer runs the linter as part of `next build`. + +## Related Technologies + +* Remix, Redwood, Gatsby, and Astro as other meta-frameworks. +* Playwright for end-to-end testing. +* Vercel Edge Functions and Cloudflare Workers for serverless. + +## Citations + +* [React](https://react.dev/) +* [Next.js project structure](https://nextjs.org/docs/app/getting-started/project-structure) +* [Biome](https://biomejs.dev/) +* [Vitest](https://vitest.dev/) + +## See Also + +* [Node.js and JavaScript](node-js.md) +* [Agent Instruction Files](../agents-files.md) diff --git a/omp-docs/engineering/languages/rust.md b/omp-docs/engineering/languages/rust.md new file mode 100644 index 0000000..7d662b0 --- /dev/null +++ b/omp-docs/engineering/languages/rust.md @@ -0,0 +1,97 @@ +--- +type: reference +title: Rust +description: Current best practices for Rust projects - cargo, editions, web frameworks, and tooling. +tags: + - rust + - cargo + - axum + - bootstrap + - engineering +timestamp: 2026-08-11 +verified: 2026-08-28 +--- + +CUT +# Rust + +This page covers current (2025/2026) best practices for Rust projects. + +## Bootstrap + +Create a binary crate: + +```bash +cargo new my-app --bin +``` + +Create a library crate: + +```bash +cargo new my-lib --lib +``` + +New projects use the Rust 2024 edition by default. + +## Tooling + +| Category | Tool | Notes | +|----------|------|-------| +| Toolchain | rustup | Install with the rustup script. | +| Formatter | rustfmt | Run `cargo fmt`. | +| Linter | clippy | Run `cargo clippy --all-targets --all-features`. | +| Testing | `cargo test` | Unit tests in `#[cfg(test)]`, integration tests in `tests/`. | +| Async runtime | tokio | The standard choice. | + +Use `cargo clippy -- -D warnings` in CI. + +## Workspaces + +Use a Cargo workspace for projects with multiple crates. Declare members in the root `Cargo.toml`. + +``` +workspace-root/ +├── Cargo.toml +└── crates/ + ├── app/ + └── core/ +``` + +## Web Frameworks + +| Framework | Best For | Notes | +|-----------|----------|-------| +| Axum 0.8 | Most Rust web apps | Most popular. Tokio team. | +| actix-web | High-throughput services | Slightly faster in benchmarks. | +| Rocket | Developer experience | Excellent ergonomics. | + +Use Axum for new web services. + +## Error Handling + +Use `thiserror` for library error types. Use `anyhow` for application-level errors. The `?` operator propagates errors. + +## Desktop and WASM + +* Use Tauri 2 for cross-platform desktop apps with a web frontend. +* Use `wasm-pack` and `wasm-bindgen` for WebAssembly. + +## Related Technologies + +* serde and serde_json for serialization. +* clap for command-line interfaces. +* tracing and tracing-subscriber for structured logging. +* sqlx for compile-time checked SQL. +* tonic for gRPC. +* criterion for benchmarks. + +## Citations + +* [The Cargo Book](https://doc.rust-lang.org/cargo/) +* [Axum](https://docs.rs/axum/) +* [Tauri](https://v2.tauri.app/) + +## See Also + +* [SDLC and Tooling](../sdlc.md) +* [Go](go.md) diff --git a/omp-docs/engineering/plugins.md b/omp-docs/engineering/plugins.md new file mode 100644 index 0000000..e80716e --- /dev/null +++ b/omp-docs/engineering/plugins.md @@ -0,0 +1,53 @@ +--- +type: reference +title: Pi Plugins +description: The pi extension ecosystem and its notable packages - subagents, web access, permission, and skills. +tags: + - pi + - plugins + - packages + - engineering +timestamp: 2026-08-11 +--- +verified: 2026-08-28 + +# Pi Plugins + +This page covers the pi coding agent extension ecosystem. Pi extends itself through npm packages installed with `pi install`. Each package provides extensions, skills, prompts, or themes. + +## How Plugins Work + +A pi plugin is an npm package that contains a `pi` manifest. The manifest points to the package's `skills/` and `extensions/` directories. The system reads the manifest at startup and loads the listed capabilities. + +Plugins install to the pi home directory. Locally installed packages in this setup include `pi-peon`, `pi-web-access`, and the core `pi-subagents` extension. See the [Pi Packages](../pi/packages/index.md) page for local details. + +## Notable Packages + +The table lists packages verified in the npm registry during research. Popularity signals are approximate and change over time. + +| Package | Purpose | +|---------|---------| +| `pi-subagents` | Core subagent delegation with chains and parallel execution. | +| `pi-web-access` | Web search, URL fetching, GitHub cloning, PDF extraction. | +| `@wierdbytes/pi-peon` | CESP/OpenPeon sound packs for lifecycle events. | +| `bigpowers` | A large collection of spec-driven development skills. | +| `pi-permission` | Layered shell command permissions. | +| `@anton-kochev/pi-skills` | Plan mode, TDD, and SRS skills (deprecated). | + +Some package names that appear in older documentation, such as `pi-browser-use` and `pi-permission-system`, did not resolve in the npm registry at research time. Verify a package name before you install it. + +## Related Ecosystem + +Pi implements the open Agent Skills standard. This makes pi skills compatible with Claude Code, Codex CLI, Amp, Droid, Cursor, and many other agents. See the [Skills Ecosystem](skills-ecosystem.md) page. + +## Citations + +* [npm registry](https://www.npmjs.com/) +* [Agent Skills standard](https://agentskills.io/) +* [vercel-labs/skills](https://github.com/vercel-labs/skills) + +## See Also + +* [Pi Configuration](../pi/index.md) +* [Pi Packages](../pi/packages/index.md) +* [Skills Documentation](../skills/index.md) diff --git a/omp-docs/engineering/sdlc.md b/omp-docs/engineering/sdlc.md new file mode 100644 index 0000000..004fef8 --- /dev/null +++ b/omp-docs/engineering/sdlc.md @@ -0,0 +1,115 @@ +--- +type: reference +title: SDLC and Tooling Best Practices +description: Current best practices for the software development life cycle - git, CI/CD, testing, review, versioning, and dev environments. +tags: + - sdlc + - git + - ci-cd + - testing + - tooling + - unverified +timestamp: 2026-08-11 +--- +verified: 2026-08-28 + +# SDLC and Tooling Best Practices + +This page distills current (2025/2026) best practices for running a software project. Use it when you bootstrap a new repository or when you review an existing one. + +## Git Branching + +Trunk-based development dominates. Teams use short-lived feature branches and merge into a single shared `main` branch. Feature flags hide incomplete features. This replaces older models such as GitFlow for most projects. + +Use GitHub Flow as the default for new projects. Create a branch for each change. Open a pull request for every change. Merge the change after review. Deploy from `main` at any time. + +The rule `main` must stay deployable at all times. + +## Continuous Integration and Delivery + +GitHub Actions is the most common CI/CD platform. Workflows live in `.github/workflows/`. A standard workflow follows this order: lint, test, build, deploy. + +Use these patterns: + +* Run one pipeline for pull request checks. +* Run a separate pipeline for `main` branch deployments. +* Use matrix builds to test multiple tool versions. +* Cache dependencies between runs. +* Split shared steps into reusable workflows. + +## Testing + +Follow the testing pyramid. Write many unit tests. Write fewer integration tests. Write the fewest end-to-end tests. + +| Layer | Speed | Focus | +|-------|-------|-------| +| Unit | Fast | Isolated functions and modules | +| Integration | Medium | Service-to-service interaction | +| End-to-end | Slow | Complete user journeys | + +Aim for roughly ten unit tests per integration test, and ten integration tests per end-to-end test. + +## Code Review + +Reduce review friction with these tools: + +* Pull request templates for consistency. +* `CODEOWNERS` to assign reviewers by path. +* Required review before merge. +* Pre-commit hooks for lint and format checks. + +## Semantic Versioning + +Version numbers follow the `MAJOR.MINOR.PATCH` format. + +* MAJOR changes when an API breaks compatibility. +* MINOR changes when features stay compatible. +* PATCH changes fix bugs in a compatible way. + +Pre-release versions use `-alpha`, `-beta`, or `-rc` suffixes. + +## Development Environments + +Use `mise` to manage tool versions, environment variables, and named tasks in one `mise.toml` file. `mise` replaces the separate tools asdf and direnv, and it replaces a `Makefile` for tasks. + +Use Dev Containers for reproducible environments. The Dev Container Specification uses `.devcontainer/devcontainer.json`. It works with VS Code, Codespaces, and the container CLI. + +## Per-Ecosystem Variations + +| Ecosystem | Manifest | Package manager | Test command | +|-----------|----------|-----------------|--------------| +| Node/JS | `package.json` | npm, pnpm, or Bun | `vitest` / `jest` | +| Python | `pyproject.toml` | uv | `pytest` | +| Rust | `Cargo.toml` | cargo | `cargo test` | +| Go | `go.mod` | go modules | `go test ./...` | +| Terraform | `.tf` files | providers | `terraform validate` | + +Put `AGENTS.md` instructions for each ecosystem in the [Agent Instruction Files](agents-files.md) page. + +## Monorepos + +Use a workspace tool for monorepos: + +* Turborepo or Nx for JavaScript/TypeScript. +* pnpm workspaces for dependency management. +* Cargo workspaces for Rust. +* Go workspaces for Go modules. +* uv workspaces for Python. + +Put a nested `AGENTS.md` in each package when a monorepo has multiple packages. + +## Citations + +* [Trunk-Based Development](https://trunk-based-development.com/) +* [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow) +* [GitHub Actions](https://docs.github.com/en/actions) +* [Microsoft Engineering Playbook](https://microsoft.github.io/code-with-engineering-playbook/) +* [semver.org](https://semver.org/) +* [mise](https://mise.jdx.dev/) +* [Dev Container Specification](https://containers.dev/) + +## See Also + +* [Agent Instruction Files](agents-files.md) +* [Language and Framework Stacks](languages/index.md) +* [Infrastructure and Cloud](infra/index.md) diff --git a/omp-docs/engineering/signal-remote.md b/omp-docs/engineering/signal-remote.md new file mode 100644 index 0000000..be8be1c --- /dev/null +++ b/omp-docs/engineering/signal-remote.md @@ -0,0 +1,116 @@ +--- +type: guide +title: Remote Control a Pi Instance with Signal +description: How to drive a self-hosted pi agent from Signal messages using signal-cli and a bridge layer. +tags: + - signal + - remote-control + - pi + - automation + - unverified +timestamp: 2026-08-11 +--- +verified: 2026-08-28 + +# Remote Control a Pi Instance with Signal + +This page explains how to send a command to a self-hosted pi agent from a Signal message. Signal has no official bot API, so you must use an open-source bridge. The bridge delivers a Signal message to the agent and then returns the agent reply over Signal. + +## Overview + +```mermaid +flowchart LR + U[Signal client] -->|Signal message| B[signal-cli-rest-api] + B -->|WebSocket or REST| G[bridge layer] + G -->|stdin or webhook| P[pi agent] + P -->|reply| G + G -->|send| B + B -->|Signal message| U +``` + +## Signal Bridges + +Signal provides no public bot platform. Use one of these open-source bridges. + +### signal-cli + +`signal-cli` is a Java command-line client. It runs in CLI, daemon, or JSON-RPC mode. Use it to register a number, link a device, send, and receive. + +Install the GraalVM native build to avoid JVM startup time: + +```bash +curl -L -O https://github.com/AsamK/signal-cli/releases/download/vVERSION/signal-cli-VERSION-Linux-native.tar.gz +``` + +Send a message: + +```bash +signal-cli -a +1234567890 send -m "Hello" +0987654321 +``` + +Receive messages: + +```bash +signal-cli -a +1234567890 daemon --http=localhost:3000 +``` + +The daemon exposes `POST /api/v1/rpc` and `GET /api/v1/events`. + +Keep `signal-cli` updated. A release older than three months can break against the Signal server. + +### signal-cli-rest-api + +`signal-cli-rest-api` wraps `signal-cli` in a Docker container. It exposes REST endpoints and a WebSocket receive channel. This is the easiest bridge to deploy. + +Run it with `MODE=json-rpc` for a single daemon with WebSocket receive. Send a message with `POST /v2/send`. Receive messages from `GET /v1/receive/<number>`. + +### signald + +`signald` is a lighter Rust alternative. It runs as a daemon and communicates over WebSocket. It uses fewer resources than the Java-based `signal-cli`. + +## Bridge the Message to the Agent + +Use one of these patterns to connect the Signal bridge to the pi agent. + +* Webhook: the bridge posts the incoming message to the agent over HTTP. +* WebSocket: a script subscribes to incoming messages and calls the agent. +* File polling: a script writes each message to a file that the agent watches. +* JSON-RPC pipe: the agent runs as a child process of the `signal-cli` daemon. + +Use a high-level framework to make the bridge simpler: + +* `signalbot` in Python. +* `signal-rest-ts` in TypeScript. + +## Account Setup + +Use a dedicated number for the bot. Register the number as its own account, or link it to your phone as a linked device. + +A primary account allows up to five linked devices. Use a dedicated secondary SIM or a landline for a self-contained bot. + +Registration requires a captcha from the Signal captcha site. Verify with an SMS code. Use voice verification for landlines. + +## Security and Gotchas + +Protect the bot keys. The bridge stores cryptographic keys in its data directory. Anyone with access to that directory can impersonate the bot. + +* Restrict the bridge to localhost. +* Use API tokens and IP filtering if you expose it. +* Use `secured-signal-api` as an authenticated gateway for internet access. + +The Signal protocol expects regular receive calls. Use daemon mode or an auto-receive schedule to keep messages in sync. Do not combine REST receive and auto-receive, or you will get duplicate messages. + +## Citations + +* [signal-cli](https://github.com/AsamK/signal-cli) +* [signal-cli-rest-api](https://github.com/bbernhard/signal-cli-rest-api) +* [signald](https://pypi.org/project/signald/) (GitHub: <https://github.com/signald/signald> — archived) +* [signalbot](https://pypi.org/project/signalbot/) +* [signal-rest-ts](https://www.npmjs.com/package/signal-rest-ts) (unverified) +* [secured-signal-api](https://github.com/codeshelldev/secured-signal-api) + +## See Also + +* [Pi Configuration](../pi/index.md) +* [Pi Subagents](../pi/packages/pi-subagents.md) +* [Agent Instruction Files](agents-files.md) diff --git a/omp-docs/engineering/skills-ecosystem.md b/omp-docs/engineering/skills-ecosystem.md new file mode 100644 index 0000000..1818b00 --- /dev/null +++ b/omp-docs/engineering/skills-ecosystem.md @@ -0,0 +1,144 @@ +--- +type: reference +title: Skills Ecosystem and Top Skills +description: The skills.sh registry, the Agent Skills ecosystem, and the verified top 50 skills by installs. +tags: + - skills + - skills-sh + - agent-skills + - ecosystem + - engineering + - unverified +--- +verified: 2026-08-28 + +# Skills Ecosystem and Top Skills + +This page covers the open agent skills ecosystem. It describes the registries, the install tooling, and the top skills by category. + +## The Ecosystem + +`skills.sh` is the primary registry and leaderboard for agent skills. It runs on the open-source `skills` CLI from Vercel Labs. Use these commands: + +```bash +npx skills add <owner/repo> # Install skills +npx skills find [query] # Search skills +npx skills list # List installed skills +``` + +The underlying standard is the Agent Skills specification at [agentskills.io](https://agentskills.io). Over 20 coding agents support it. A single `SKILL.md` works across these agents. + +Related registries: + +| Registry | Focus | +|----------|-------| +| skills.sh | Primary registry and leaderboard. | +| agentskill.sh | Directory and marketplace with many indexed skills. | +| officialskills.sh | Verified skills from major organizations. | +| qaskills.sh | QA and testing skills. | + +Use the local `npx skills` command to explore what is available. You can query the leaderboard data directly at `GET /api/skills/all-time/{page}` on skills.sh. The page index is zero-based and returns 200 skills per page. + +## Top 50 Skills by All-Time Installs + +The table lists the top 50 skills verified from the live skills.sh API on 2026-08-12. Install counts are exact at query time. + +| # | Skill | Source | Installs | +|----|-------|--------|----------| +| 1 | `find-skills` | vercel-labs/skills | 2,918,155 | +| 2 | `grill-me` | mattpocock/skills | 832,797 | +| 3 | `frontend-design` | anthropics/skills | 767,871 | +| 4 | `grill-with-docs` | mattpocock/skills | 708,703 | +| 5 | `improve-codebase-architecture` | mattpocock/skills | 683,652 | +| 6 | `tdd` | mattpocock/skills | 660,660 | +| 7 | `agent-browser` | vercel-labs/agent-browser | 659,465 | +| 8 | `vercel-react-best-practices` | vercel-labs/agent-skills | 625,739 | +| 9 | `setup-matt-pocock-skills` | mattpocock/skills | 607,703 | +| 10 | `handoff` | mattpocock/skills | 570,592 | +| 11 | `triage` | mattpocock/skills | 568,784 | +| 12 | `lark-doc` | open.feishu.cn | 561,794 | +| 13 | `lark-approval` | open.feishu.cn | 561,758 | +| 14 | `lark-base` | open.feishu.cn | 561,634 | +| 15 | `lark-drive` | open.feishu.cn | 561,452 | +| 16 | `lark-shared` | open.feishu.cn | 561,337 | +| 17 | `lark-calendar` | open.feishu.cn | 561,273 | +| 18 | `lark-im` | open.feishu.cn | 561,248 | +| 19 | `lark-contact` | open.feishu.cn | 561,157 | +| 20 | `lark-sheets` | open.feishu.cn | 561,006 | +| 21 | `lark-wiki` | open.feishu.cn | 560,924 | +| 22 | `lark-attendance` | open.feishu.cn | 560,891 | +| 23 | `lark-event` | open.feishu.cn | 560,888 | +| 24 | `lark-minutes` | open.feishu.cn | 560,818 | +| 25 | `lark-openapi-explorer` | open.feishu.cn | 560,777 | +| 26 | `lark-whiteboard` | open.feishu.cn | 560,768 | +| 27 | `lark-mail` | open.feishu.cn | 560,720 | +| 28 | `lark-task` | open.feishu.cn | 560,692 | +| 29 | `lark-slides` | open.feishu.cn | 560,590 | +| 30 | `lark-skill-maker` | open.feishu.cn | 560,554 | +| 31 | `lark-vc` | open.feishu.cn | 560,466 | +| 32 | `lark-workflow-meeting-summary` | open.feishu.cn | 560,368 | +| 33 | `lark-workflow-standup-report` | open.feishu.cn | 560,358 | +| 34 | `prototype` | mattpocock/skills | 556,403 | +| 35 | `lark-okr` | open.feishu.cn | 541,430 | +| 36 | `web-design-guidelines` | vercel-labs/agent-skills | 535,426 | +| 37 | `lark-markdown` | open.feishu.cn | 526,555 | +| 38 | `microsoft-foundry` | microsoft/azure-skills | 523,287 | +| 39 | `azure-diagnostics` | microsoft/azure-skills | 518,052 | +| 40 | `azure-ai` | microsoft/azure-skills | 517,867 | +| 41 | `azure-deploy` | microsoft/azure-skills | 517,694 | +| 42 | `azure-prepare` | microsoft/azure-skills | 517,512 | +| 43 | `azure-validate` | microsoft/azure-skills | 517,228 | +| 44 | `azure-storage` | microsoft/azure-skills | 516,821 | +| 45 | `entra-app-registration` | microsoft/azure-skills | 516,567 | +| 46 | `appinsights-instrumentation` | microsoft/azure-skills | 516,335 | +| 47 | `azure-resource-lookup` | microsoft/azure-skills | 516,249 | +| 48 | `azure-compliance` | microsoft/azure-skills | 516,198 | +| 49 | `azure-aigateway` | microsoft/azure-skills | 516,058 | +| 50 | `azure-kusto` | microsoft/azure-skills | 515,980 | + +## Notable Categories + +The top 50 breaks down into these groups: + +* Development workflow: find-skills, grill-me, tdd, handoff, triage, prototype. +* Design and frontend: frontend-design, vercel-react-best-practices, web-design-guidelines. +* Lark office suite: 22 skills from open.feishu.cn, roughly ranks 12-35. +* Azure infrastructure: 13 skills from microsoft/azure-skills, ranks 38-50. +* Agent orchestration: agent-browser, setup-matt-pocock-skills. + +`find-skills` leads by a wide margin with 2.9 million installs. The Lark suite and Azure suite dominate the middle of the list. + +## SKILL.md Format + +A skill is a directory that contains a `SKILL.md` file: + +```yaml +--- +name: my-skill +description: What this skill does +--- +``` + +The `name` field is required and lowercase. The `description` field is required. Skills load progressively: discovery loads only the metadata, activation loads the full file on match. + +## 2025/2026 Trends + +* The Agent Skills spec is the common standard across 20+ agents. +* Skills are write once, use everywhere. +* Registries add security audits for skill content. +* Specialized registries, such as QA, are emerging. + +## Citations + +* [skills.sh](https://skills.sh) +* [skills.sh API `/api/skills/all-time/0`](https://skills.sh/api/skills/all-time/0) +* [vercel-labs/skills](https://github.com/vercel-labs/skills) +* [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) +* [agentskills.io](https://agentskills.io) +* [openai/skills](https://github.com/openai/skills) + +## See Also + +* [Agent Instruction Files](agents-files.md) +* [Pi Plugins](plugins.md) +* [Skills Documentation](../skills/index.md) diff --git a/omp-docs/index.md b/omp-docs/index.md new file mode 100644 index 0000000..0855945 --- /dev/null +++ b/omp-docs/index.md @@ -0,0 +1,54 @@ +# Command Center Knowledge Base + +System configuration knowledge base for Frank's fleet (Dankware, Dankclaw, +Dankserver) and the agent tooling that runs on it. Every concept has its own +file; every directory index links its complete contents. Format: OKF v0.1 — +a directory of markdown files with YAML frontmatter (see +[references/okf-spec.md](references/okf-spec.md)). + +Verification discipline: facts carry `verified:` stamps when probed against the +live fleet, and an `unverified` tag where a claim could not be checked on +2026-08-28. Trust stamped facts over memory; re-verify before acting on +`unverified` ones. + +## [System](system/index.md) + +Hardware, OS, and network of the three-box fleet — verified against live probes +on 2026-08-28. + +## [Caddy](caddy/index.md) + +The reverse proxy fronting every service on both servers (Podman Quadlet, +Porkbun DNS-01, hot reload). + +## [Gitea and tooling](tools/index.md) + +Installed software: Gitea, llama.cpp/ornith, niri, ghostty, tmux, ComfyUI, +CachyOS, skills tooling — each with its verified operational facts. + +## [Pi-era agent setup](pi/index.md) + +The legacy pi agent configuration (~/.pi era): settings, models, packages, +skills. Kept for reference; the live harness is OMP under `~/.omp`. + +## [OMP packages and skills](packages/index.md), [skills index](skills/index.md) + +Extensions and skills installed for the current OMP harness. + +## [Core config](core/index.md) + +The live agent configuration itself: settings, models, AGENTS.md conventions. + +## [Engineering references](engineering/index.md) + +Practice notes: SDLC, languages, infra tooling (Terraform, K8s, containers). + +## [Research](research/index.md) + +Decision-support research: agentic web tooling, chezmoi evaluation, +secrets-for-agents. Research docs inform decisions; they are not facts yet. + +## [Inventory](inventory/index.md) + +Pre-pruning census of every userspace config on this box — the input for the +pruning session. diff --git a/omp-docs/inventory/home-config-census.md b/omp-docs/inventory/home-config-census.md new file mode 100644 index 0000000..17d615f --- /dev/null +++ b/omp-docs/inventory/home-config-census.md @@ -0,0 +1,241 @@ +--- +type: reference +title: Home Directory Configuration Census +description: Complete inventory of userspace program configurations on Dankware — top-level dotfiles, ~/.config, ~/.local/share state, and special directories (~/.pi, ~/.omp). +tags: [inventory, unverified, census, dotfiles, config] +created: 2026-08-28 +census-date: 2026-08-28 +source: Dankware CachyOS laptop +--- + +## Scope & Methodology + +Census covers four areas: (1) top-level dotfiles/dotdirs in `/home/dank` (excluding `.omp` which is documented separately here), (2) every entry under `~/.config`, (3) non-cache state dirs under `~/.local/share`, (4) special directories `~/.pi` and `~/.omp`. Each entry assessed for installed status (`command -v`), size (`du -sh`), and age (mtime). Uninstalled programs flagged as `prune-candidate`. + +All measurements are live — no invented numbers. + +--- + +## 1. Top-Level Dotfiles / Dotdirs + +> 38 entries in `/home/dank` beginning with `.` (excluding `.omp`). + +| Path | What it is | Installed? | Size | Age (mtime) | Prune? | +|---|---|---|---|---|---| +| `.bash_history` | Bash command history | yes (bash) | 12K | 2026-08-27 | — | +| `.bash_logout` | Bash logout script | yes (bash) | 4.0K | 2026-07-03 | — | +| `.bash_profile` | Bash login script | yes (bash) | 4.0K | 2026-07-03 | — | +| `.bashrc` | Bash config | yes (bash) | 4.0K | 2026-07-12 | — | +| `.bun` | Bun runtime install | yes | 2.3G | 2026-07-05 | — | +| `.cache` | XDG cache directory | system | 6.4G | 2026-08-28 | — | +| `.claude` | Claude Code config | **no** | 6.4M | 2026-07-12 | **prune-candidate** | +| `.config` | XDG config directory | system | 574M | 2026-08-25 | — | +| `.env` | Environment variables | system | 4.0K | 2026-08-21 | — | +| `.git-credentials` | Git auth cache | yes (git) | 4.0K | 2026-08-28 | — | +| `.gitconfig` | Git global config | yes (git) | 4.0K | 2026-08-05 | — | +| `.local` | XDG local directory | system | 552G | 2026-07-24 | — | +| `.npm` | Node package manager cache | yes (node) | 1.7G | 2026-07-23 | — | +| `.nv` | nvim (Neovim) config | **no** | 8.0K | 2026-07-03 | **prune-candidate** | +| `.nvidia-settings-rc` | NVIDIA Settings config | yes | 4.0K | 2026-07-04 | — | +| `.nvm` | Node Version Manager | **no** | 256M | 2026-07-06 | **prune-candidate** | +| `.openpeon` | OMP Peon session state | yes (omp) | 4.4M | 2026-07-16 | — | +| `.p10k.zsh` | Powerlevel10k zsh theme | yes (zsh) | 96K | 2026-07-03 | — | +| `.paradoxlauncher` | Paradox Launcher state | **no** | 1.1G | 2026-07-31 | **prune-candidate** | +| `.pi` | Legacy PI agent (git repo) | — | 2.5G | 2026-08-17 | see §4 | +| `.pki` | System PKI certs | system | 120K | 2026-07-03 | — | +| `.pulse-cookie` | PulseAudio session | system | 4.0K | 2026-07-03 | — | +| `.python_history` | Python REPL history | yes (python3) | 4.0K | 2026-08-06 | — | +| `.ssh` | SSH keys & config | yes | 28K | 2026-08-24 | — | +| `.steam` | Steam runtime + config | yes | 44K | 2026-08-26 | — | +| `.steampath` | Steam executable path | yes (steam) | 4.0K | 2026-07-31 | — | +| `.steampid` | Steam PID file | yes (steam) | 4.0K | 2026-07-31 | — | +| `.tmux-resurrect` | Tmux resurrect state | yes (tmux) | 0 | 2026-08-25 | — | +| `.tmux.conf` | Tmux configuration | yes (tmux) | 4.0K | 2026-07-18 | — | +| `.wget-hsts` | Wget HSTS database | yes (wget) | 4.0K | 2026-07-06 | — | +| `.zcompdump-dankware-5.9.1` | Zsh completions v5.9.1 | yes (zsh) | 56K | 2026-07-12 | — | +| `.zcompdump-dankware-5.9.1.zwc` | Zsh compiled completions v5.9.1 | yes (zsh) | 120K | 2026-07-12 | — | +| `.zcompdump-dankware-5.9.2` | Zsh completions v5.9.2 | yes (zsh) | 56K | 2026-08-19 | — | +| `.zcompdump-dankware-5.9.2.lock` | Zsh completions lock | yes (zsh) | 0 | 2026-08-25 | — | +| `.zcompdump-dankware-5.9.2.zwc` | Zsh compiled completions v5.9.2 | yes (zsh) | 120K | 2026-08-19 | — | +| `.zsh_history` | Zsh command history | yes (zsh) | 68K | 2026-08-28 | — | +| `.zshrc` | Zsh configuration | yes (zsh) | 4.0K | 2026-08-25 | — | + +--- + +## 2. ~/.config — Program Configuration Directory + +> 38 entries (30 directories + 8 standalone files) under `~/.config`. Files like `mimeapps.list`, `user-dirs.dirs`, `background`, etc. are XDG desktop integration files, not program configs. + +### Programs (directories with config files) + +| Path | What it is | Installed? | Size | Files | Age | Prune? | +|---|---|---|---|---|---|---| +| `.config/alacritty` | Alacritty terminal emulator | yes | 4.0K | 1 | 2026-07-24 | — | +| `.config/btop` | btop system monitor | yes | 12K | 1 | 2026-08-11 | — | +| `.config/cachyos` | CachyOS distro config | system | 8.0K | 3 | 2026-07-03 | — | +| `.config/chromium` | Chromium browser | yes | 158M | 423 | 2026-07-15 | — | +| `.config/chromium-headless` | Chromium headless | **no** | 2.6M | 165 | 2026-07-20 | **prune-candidate** | +| `.config/dconf` | Dconf database | yes | 4.0K | 1 | 2026-07-03 | — | +| `.config/fish` | Fish shell config | yes | 24K | 3 | 2026-07-06 | — | +| `.config/gh` | GitHub CLI config | yes | 8.0K | 2 | 2026-07-12 | — | +| `.config/ghostty` | Ghostty terminal emulator | yes | 24K | 3 | 2026-08-24 | — | +| `.config/glow` | Glow markdown renderer | yes | 4.0K | 1 | 2026-07-03 | — | +| `.config/google-chrome-for-testing` | Google Chrome (testing) | **no** | 4.0K | 1 | 2026-07-03 | **prune-candidate** | +| `.config/gtk-3.0` | GTK 3.0 theme settings | system | 12K | 3 | 2026-07-03 | — | +| `.config/gtk-4.0` | GTK 4.0 theme settings | system | 12K | 3 | 2026-07-03 | — | +| `.config/micro` | Micro text editor | yes | 696K | 154 | 2026-08-17 | — | +| `.config/mozilla` | Firefox preferences | yes | 334M | 2,918 | 2026-08-24 | — | +| `.config/nautilus` | Nautilus file manager | yes | 4.0K | 0 | 2026-07-03 | — | +| `.config/niri` | Niri Wayland WM | yes | 44K | 9 | 2026-07-15 | — | +| `.config/noctalia` | Noctalia game config | yes | 212K | 28 | 2026-07-05 | — | +| `.config/nvim` | Neovim config | yes | 64K | 13 | 2026-07-23 | — | +| `.config/obsidian` | Obsidian note-taking app | yes | 79M | 139 | 2026-08-24 | — | +| `.config/pulse` | PulseAudio config | system | 4.0K | 1 | 2026-07-03 | — | +| `.config/qBittorrent` | qBittorrent torrent client | yes | 24K | 5 | 2026-08-05 | — | +| `.config/qmd` | QMD (bun-based CLI) | yes | 4.0K | 1 | 2026-07-03 | — | +| `.config/rpiv-web-tools` | RPi web tools config | yes | 4.0K | 1 | 2026-07-03 | — | +| `.config/shelly` | Shelly home automation | yes | 8.0K | 2 | 2026-07-03 | — | +| `.config/unity3d` | Unity game engine config | yes | 188K | 3 | 2026-07-05 | — | +| `.config/vlc` | VLC media player | yes | 96K | 2 | 2026-07-03 | — | + +### Desktop / XDG Integration (no owning program) + +| Path | What it is | Installed? | Size | Age | +|---|---|---|---|---| +| `.config/autostart` | XDG autostart entries | system | 0 | 2026-07-03 | +| `.config/background` | Desktop background setting | system | 0 | 2026-07-03 | +| `.config/cachyos-hello.json` | CachyOS welcome JSON | system | 0 | 2026-07-03 | +| `.config/menus` | XDG menu spec | system | 0 | 2026-07-03 | +| `.config/mimeapps.list` | MIME handler associations | system | 0 | 2026-07-03 | +| `.config/paradox-launcher-v2` | Paradox Launcher v2 config | **no** | 0 | 2026-08-05 | **prune-candidate** | +| `.config/pavucontrol.ini` | PulseAudio Volume Control config | system | 0 | 2026-07-03 | +| `.config/spectaclerc` | Spectacle screenshot tool config | system | 0 | 2026-07-03 | +| `.config/systemd` | User systemd config | system | 16K | 2026-07-06 | — | +| `.config/user-dirs.dirs` | XDG user directory dirs | system | 0 | 2026-07-03 | +| `.config/user-dirs.locale` | XDG locale | system | 0 | 2026-07-03 | + +--- + +## 3. ~/.local/share — Non-Cache State & Config + +> 26 entries. Excluded pure caches; included game data dirs, launcher configs, and application state. + +| Path | What it is | Installed? | Size | Age | Prune? | +|---|---|---|---|---|---| +| `.local/share/Colossal Order` | Cities: Skylines 2 game data | via steam | 27M | 2026-08-26 | — | +| `.local/share/Larian Studios` | Baldur's Gate 3 game data | via steam | 1.5G | 2026-08-25 | — | +| `.local/share/Paradox Interactive` | Paradox game saves/config | via steam/flatpak | 34M | 2026-08-26 | — | +| `.local/share/Shelly` | Shelly home automation data | yes | 4.0K | 2026-07-03 | — | +| `.local/share/Steam` | Steam library + runtime | yes | 550G | 2026-08-28 | — | +| `.local/share/Trash` | Desktop trash | system | 424M | 2026-08-27 | — | +| `.local/share/Tropico6` | Tropico 6 game data | via steam | 3.1M | 2026-08-26 | — | +| `.local/share/applications` | Desktop entry files | system | 56K | 2026-07-03 | — | +| `.local/share/com.pais.handy` | Handy app (likely flatpak) | unknown | 140K | 2026-08-25 | — | +| `.local/share/desktop-directories` | XDG desktop dirs | system | 0 | 2026-07-03 | — | +| `.local/share/fish` | Fish shell data | yes | 4.0K | 2026-07-03 | — | +| `.local/share/flatpak` | Flatpak runtime/pkgs | yes | 8.0K | 2026-07-03 | — | +| `.local/share/gvfs-metadata` | GVFS metadata | system | 156K | 2026-08-25 | — | +| `.local/share/icons` | XDG icon theme data | system | 1.1M | 2026-07-03 | — | +| `.local/share/inxi` | Inxi system info data | yes | 0 | 2026-07-03 | — | +| `.local/share/keyrings` | System keyring data | system | 8.0K | 2026-07-03 | — | +| `.local/share/nautilus` | Nautilus state | yes | 164K | 2026-07-03 | — | +| `.local/share/noctalia` | Noctalia game state | yes | 48K | 2026-08-25 | — | +| `.local/share/nvim` | Neovim local data | yes | 186M | 2026-08-25 | — | +| `.local/share/qBittorrent` | qBittorrent download state | yes | 8.5M | 2026-08-05 | — | +| `.local/share/sddm` | SDDM display manager state | system | 4.0K | 2026-07-03 | — | +| `.local/share/shelly-icons` | Shelly icon assets | yes | 67M | 2026-07-03 | — | +| `.local/share/uv` | UV (Python) package data | yes | 59M | 2026-07-03 | — | +| `.local/share/vlc` | VLC cache/state | yes | 4.0K | 2026-07-03 | — | +| `.local/share/vulkan` | Vulkan shader cache | system | 16K | 2026-07-03 | — | + +--- + +## 4. Special Directories + +### ~/.pi — Legacy PI Agent (git repo) + +> 31 entries. **2.5G total.** Remote: `dankclaw:3000/dank/agent.git`. Last commit: `eda2edb docs: update frank-default-large model to Qwen3.8-Flash-Next Uncensored ROCmFP4 STRIX_LEAN`. + +**Top-level contents:** + +| Path | What it is | Size | Prune? | +|---|---|---|---| +| `agent/` | PI agent core — git-tracked code, sessions, node_modules | 2.2G | — | +| `browser-profile/` | Chromium browser profile (artifacts) | 200M | **prune-candidate** | +| `trash/` | Agent session trash | 1.8M | **prune-candidate** | +| `docs/` | Documentation | 684K | — | +| `npm/` | NPM global packages | 368K | — | +| `knowledge/` | Knowledge base | 120K | — | +| `skills/` | Agent skills | 112K | — | +| `scripts/` | Agent scripts | 92K | — | +| `extensions/` | Agent extensions | 60K | — | +| `system-agent-prompts-guide.md` | Agent prompt guide | 56K | — | +| `research/` | Research artifacts | 44K | **prune-candidate** | +| `okf-*.md` | OKF project documents (6 files) | ~96K total | — | +| `web-search.json` | Web search config | 4.0K | — | +| `trust.json` | Trust registry | 4.0K | — | +| `skills-lock.json` | Skills lock file | 4.0K | — | +| `settings.json` / `settings.json.save` | Agent settings | 8.0K total | — | +| `peon` | Peon integration | 4.0K | — | +| `oldAGENTS.md` | Legacy AGENTS.md | 4.0K | — | +| `keybindings.json` | Key bindings | 4.0K | — | +| `PROMPTS` | Prompt templates | 4.0K | — | +| `AGENTS.md` | Agent config | 4.0K | — | +| `web-search-cache` | Search cache (empty) | 0 | **prune-candidate** | + +**Size offenders inside `agent/` (≥10M):** + +| File | Size | +|---|---| +| `agent/npm/node_modules/onnxruntime-node/bin/.../libonnxruntime_providers_cuda.so` | 302M | +| `agent/npm/node_modules/@lancedb/lancedb-linux-x64-gnu/lancedb.linux-x64-gnu.node` | 137M | +| `.git/objects/pack/pack-ff7cc5418a978a5839d587472bec385f4c9ce72d.pack` | 81M | +| `agent/npm/node_modules/onnxruntime-node/bin/napi-v6/...` (multi-platform binaries) | 56M | +| `agent/npm/node_modules/webgpu/dist/...` (multi-platform .node) | 55M | +| `agent/npm/node_modules/pdf-oxide-wasm/...` (Wasm bundles) | 51M | +| `agent/npm/node_modules/onnxruntime-web/dist/` (Wasm runtime) | 43M | +| `agent/sessions/--home-dank-Projects-*/...` (session JSONL files) | 80M+ | +| `agent/npm/node_modules/playwright-core/lib/` (browser bundle) | 6.1M | + +**Prune candidates flagged by task scope:** +- `research/` (44K) — research artifacts, likely stale +- `browser-profile/` (200M) — browser profile, not needed for agent +- `trash/` (1.8M) — agent session trash, purgeable + +### ~/.omp — Command Center + +> **411M.** Git repo, 7,726,074 commits. Remote: `192.168.0.143:3000/dank/command-center.git`. Last commit: `7726074 chore: birth — state-out ignore policy + secret-gate pre-commit hook`. Active configuration center for the OMP harness — **do not prune.** + +--- + +## Summary + +| Metric | Value | +|---|---| +| **Total config items** | 133 (38 top-level + 38 ~/.config + 26 ~/.local/share + 27 ~/.pi top-level entries + 1 ~/.omp) | +| **Orphaned configs** (owning program uninstalled) | **7** (.claude, .nv, .nvm, .paradoxlauncher at top-level; chromium-headless, google-chrome-for-testing, paradox-launcher-v2 in ~/.config) | +| **Total storage for configs** | ~567M (dotfiles) + 574M (~/.config) + 765M (~/.local/share excl. Steam) + 2.5G (~/.pi) = **~4.4G** | +| **Steam library** | 550G (not counted in config total — it's game data) | + +### Top 10 Largest Offenders by du -sh + +| Rank | Path | Size | Notes | +|---|---|---|---| +| 1 | `~/.local/share/Steam/` | 550G | Game library (not config) | +| 2 | `~/.cache/` | 6.4G | System cache | +| 3 | `~/.pi/` | 2.5G | Legacy agent (git repo) | +| 4 | `~/.bun/` | 2.3G | Bun runtime | +| 5 | `~/.npm/` | 1.7G | Node modules cache | +| 6 | `~/.local/share/Larian Studios/` | 1.5G | Baldur's Gate 3 (via Steam) | +| 7 | `~/.omp/` | 411M | Command center (keep) | +| 8 | `~/.local/share/Trash/` | 424M | Desktop trash | +| 9 | `~/.config/mozilla/` | 334M | Firefox profile | +| 10 | `~/.local/share/nvim/` | 186M | Neovim data/cache | + +### Prune Summary + +| Category | Count | Entries | +|---|---|---| +| Full program uninstalled | 7 | .claude, .nv, .nvm, .paradoxlauncher, chromium-headless, google-chrome-for-testing, paradox-launcher-v2 | +| Stale session/trash data | 3 | .pi/trash, .pi/browser-profile, .pi/research | +| **Total recommended for review** | **10** | — | diff --git a/omp-docs/inventory/index.md b/omp-docs/inventory/index.md new file mode 100644 index 0000000..9f41d0b --- /dev/null +++ b/omp-docs/inventory/index.md @@ -0,0 +1,5 @@ +# Inventory Index + +Census of all userspace program configuration on Dankware. + +- [home-config-census.md](home-config-census.md) — Complete inventory of top-level dotfiles, ~/.config, ~/.local/share state, and special directories (~/.pi, ~/.omp) diff --git a/omp-docs/log.md b/omp-docs/log.md new file mode 100644 index 0000000..31c16e1 --- /dev/null +++ b/omp-docs/log.md @@ -0,0 +1,238 @@ +--- +type: changelog +title: Bundle Change Log +description: Chronological update history for the OKF knowledge bundle. +tags: + - okf + - maintenance + - changelog +timestamp: 2026-08-28 +--- + +# Bundle Change Log + +## 2026-09-01 — Retry backoff and thinking default + +* **Retry backoff**: configured Pi's automatic agent-level retries in `settings.json` with a 10-second base delay, producing 10s, 20s, and 40s delays across three retries. +* **Thinking default**: set `settings.json` `defaultThinkingLevel` to `medium`. `models.json` has no supported per-model default-thinking field; Pi applies this global default to the configured models. + + +## 2026-08-28 — KB rebuilt to OKF v0.1; live-verified fleet facts + +* **Creation**: the whole `omp-docs/` bundle was copied from the legacy `~/.pi/agent/docs` tree and rebuilt as a git-tracked, OKF v0.1-conformant knowledge base inside the new `command-center` repo (repo root = live agent dir; the checkout *is* the deployment). Every checkable claim was re-verified against the live fleet (read-only probes); unverifiable claims are tagged `unverified` in frontmatter. +* **Update — hardware facts corrected**: Dankserver is a **Ryzen 7 7700X + RTX 3090** (not Strix Halo); Strix Halo (gfx1151) is **Dankclaw**. RAM, storage, kernel, and network facts were probed live and corrected across `system/`. +* **Update — conformance pass**: concept-in-disguise indexes promoted to `<dirname>.md` concept files (identity = path, per spec); index.md files stripped of frontmatter (indexes carry none); all wikilinks and relative links resolved or repointed; `scripts/kb-lint.sh` (OKF conformance + link-integrity linter) exits 0 on the bundle. Vendored `references/okf-spec.md` is exempt from link-lint — its example paths are illustrations, not links. +* **Update — inventory**: home-config census (7 orphaned configs, 10 prune-candidates) recorded under `inventory/` for the pruning session; zero deletions performed. Legacy `~/.pi` tree left untouched and frozen. +* **Deferred to operator** (decisions, not facts): chezmoi source layout (`research/chezmoi-evaluation.md` recommends a separate chezmoi repo) and the permanent secrets tool (`research/secrets-for-agents.md`; interim = pre-commit secret gate + quarantine list; top candidate sops+age). Gitea Projects unit is disabled instance-wide, so the kanban board is a one-time web-UI setup for the operator. +## 2026-08-23 — Homepage deployed to production; Caddy KB doc + +* **Homepage is live on Dankclaw.** `./scripts/deploy.sh dankclaw` deploys the static files to `/srv/homepage`, installs the status checker (systemd timer, every 3 min, writes `status.json`), writes `deployed.js` (the last master deployment datetime), renders the Caddyfile (both basicauth hashes from the host `.env`), reloads Caddy, and checks health. Verified end-to-end: `/admin/` (operator) + all shared files serve 200 under the operator credential; `/` and `/admin/` 401 without/wrong credentials; the LLM is healthy. +* **Caddyfile auth design (the hard-won fix).** Caddy *sorts* top-level directives, so a `rewrite` runs before a `basicauth`; the rewrite changed `/admin/` to `/admin.html` and the path-based auth matchers then saw the rewritten path, applying the wrong (family) auth block — the operator password 401'd. Fix: serve each page from its own `handle` block (which preserves file order, so the auth is checked on the original path): `handle /admin*` (operator only), `handle @data` (shared data + assets, family OR operator, so the admin page's fetches reuse the operator credential), and a catch-all `handle` (family). Also: a `handle` inline matcher is a single token (multi-path needs a named matcher); a leading `@name <directive>` is parsed as a matcher *definition* (re-defines `@name`). +* **Caddy mount fix.** The caddy container mounted the repo's `shared/homepage` (static source) to `/srv/homepage`; the generated files (`status.json`, `deployed.js`) are written to the host's `/srv/homepage`. Pointed the mount at the host's `/srv/homepage` so the generated files serve. A compose change needs a container *recreate* (not a reload) — `podman compose up -d caddy` (the deploy skips the compose restart, so this is manual). +* **Caddy KB doc** (operator request: read the docs before guessing at syntax): new `caddy/` section in this bundle — [[caddyfile|caddyfile]] (`caddy/caddyfile.md`) + `caddy/index.md`, cross-linked from the root `index.md`. Grounded in caddyserver.com (fetched 2026-08-23) + a researcher subagent brief. +* **Tests:** 116 green (was 112; +4 for the Caddyfile handle design + the `status.json` 0644 perms). The local `caddy validate` test is skipped (no local caddy binary); the rendered config is validated on the target via the porkbun image before each deploy. + +## 2026-08-23 — Homepage design settled (grilling complete) + +* **All 38 open questions (Q6–Q43) answered.** The homepage design is now fully settled. Full record: `serverAppConfigs/docs/Infrastructure/Homepage Design Grilling.md` (final decisions + the deltas) and `docs/Infrastructure/Homepage.md`. +* **Key deltas from the initial recommendations:** the probe method is **per service** (`tcp` or `http`); the probe timeout is **5 s**; the layout is **TUI-style panels** (a grid), not a flat list; styling is **toggleable** (full theme default, a toggle to bare unstyled HTML); **do not alter the user's cursor**; **no client-side auto-refresh** (read `status.json` once on load); the footer shows the **last master deployment datetime** (not last-check); the deploy is **git-driven** (master = deployed state); the build is **full TDD**. +* **Per-service docs workstream:** each service gets a `/docs/<svc>/` page (not `/usage/`), written as a **how-to for a regular user** (no maintenance details), password-protected by the same auth as its homepage section, built as each service goes active. The existing reference docs in `docs/` are NOT linked from the homepage (they may contain secrets). +* **Build complete (all 6 slices, full TDD, 112 tests green):** 1 the checker core (tcp/wip/atomic write/generated_at), 2 the http probe, 3 the real `services.json` + schema, 4 the pages + theme + toggle, 5 the Caddyfile auth split (root vs `/admin/`), 6 the git-driven deploy. All committed + pushed. The render logic is verified with a Node DOM shim (9 user panels, correct summary, correct footer datetime). +* **To go live:** the operator adds `CADDY_ADMIN_HASH` (the operator-only password, `caddy hash-password`) to the Dankclaw `.env`, then runs `./scripts/deploy.sh dankclaw`. Until then the admin hash stays a placeholder. The per-service `/docs/` pages, the *arr stack, and the optional `/how/` page remain separate threads. +* **Correction (media stack):** the Dankserver media stack (RomM, Copyparty, Jellyfin, Plex, the *arr) is **UP** — it runs as **bare processes/services, not yet migrated to podman containers**. The 2026-08-22 "down / missing `.env`" finding was wrong: I was probing for the compose stack, which is not how it runs yet. Do not treat it as an outage and do not probe it as down. Its podman migration is a separate, future effort. + +## 2026-08-22 — vllmScripts merged into serverAppConfigs + +* **Repo merge**: the `vllmScripts` repo (LLM inference fleet: serve scripts, systemd units, env tunables, deploy runbook, research docs) is merged into `serverAppConfigs` with its full git history (two-parent import commit, then reorganization: `docs/` → `docs/LLM/`, `scripts/` merged, `old/` for retired PP/NPU-era scripts). One repo, one checkout per host (`/home/dank/serverAppConfigs`), one `scripts/deploy.sh` covering both workloads per target (podman stack + LLM service relink/restart + both health checks). +* **Units**: frank-default-{small,large,npu}.service now point at `/home/dank/serverAppConfigs/scripts/...`. The retired target checkouts (`/home/dank/vLLM` on Dankserver, `/home/dank/vllmScripts` on Dankclaw) are to be archived on the hosts during the production deploy. +* **Secrets**: the live sudo password that the old vllmScripts AGENTS.md documented in plaintext is NOT carried into the merged repo (a bats leak-check guards it). It remains in the git history of both repos on the LAN Gitea — rotation recommended. +* **KB links**: `system/index.md`, `system/dankserver.md`, `system/dankclaw.md`, and the root `index.md` updated — the "sibling knowledge bases" section is now a single sibling (serverAppConfigs, which contains the LLM fleet KB at `docs/LLM/index.md`). +* **Port move**: `frank-default-large` (dankclaw) moved from `:52625` to `:7770` (operator request: the primary inference server sits on the standard llama.cpp port). Both LLM services now listen on `:7770`, distinguished by host. `models.json` (`llamacpp (dankclaw)`) and the OpenWebUI quadlet (`OPENAI_API_BASE_URL`) re-pointed to `:7770`. `pi/models.md` updated. +* **Homepage design (grilling)**: the `serverAppConfigs` homepage (`docs/Infrastructure/Homepage.md`) is WIP — the Caddy site is live (basicauth 401, `:80` 302) but `/srv/homepage/` is not deployed. Settled design: a single site on Dankclaw (root = user services, `/admin/` = admin services behind a second operator-only password, optional `/how/` tourist page). Status is checked **server-side** — a systemd-timer checker (every 3 min) probes each backend `host:port` and writes a same-origin `status.json`; the page reads only that file (the client-side-ping design is blocked by cross-origin + mixed-content + auth). Full decision log + 38 open questions (Q6–Q43) in `docs/Infrastructure/Homepage Design Grilling.md`. A terminal-TUI-styled HTML progress report was generated for the operator to review and answer the open questions. Full-stack baseline verified: Dankclaw fully up; the Dankserver media stack is down (only Calibre-Web + the LLM are up; no `.env` on the target). + +## 2026-08-21 — Fleet ops: passwordless sudo, Hermes SSH keys, sibling KB links + +* **Passwordless sudo**: added `/etc/sudoers.d/dank-nopasswd` (`dank ALL=(ALL) NOPASSWD: ALL`) on both Dankserver and Dankclaw. Verified `sudo -n true` on both. The pre-existing drop-ins (`frank-small` on Dankserver; `frank-large` + `frank-ling` on Dankclaw) grant per-command NOPASSWD for the frank restart scripts and remain in place. +* **Hermes SSH keys**: the Hermes Agent (podman container `hermes`, project `dankclaw` in `serverAppConfigs`, gateway drops to container uid 10000 = host uid 109999, HOME `/opt/data` on a podman volume) now has a dedicated ed25519 key at `/opt/data/.ssh/id_ed25519` (`hermes-agent@dankclaw`) plus an SSH config for `dankclaw` (192.168.0.143), `dankserver` (192.168.0.235), and `dankware` (192.168.0.226). The public key is in `dank`'s `authorized_keys` on all three machines. Verified from inside the container as the hermes user: all three `ssh <host> hostname` calls succeed. +* **Sibling KB links**: `system/index.md`, `system/dankserver.md`, `system/dankclaw.md`, and the root `index.md` now link the two sibling knowledge bases on dankware: `~/Projects/vllmScripts/` (inference fleet scripts + runbook, index `docs/index.md`) and `~/Projects/serverAppConfigs/` (Podman deploy configs for both servers, index `docs/index.md`). + +## 2026-08-19 — pi-web-access: SearXNG endpoint re-pointed to dankclaw + +* **Config**: `~/.pi/web-search.json` — `searxngBaseUrl` moved from the dead `192.168.0.235:8081` (dankserver, connection refused) to `192.168.0.143:8081` (dankclaw; verified live: HTTP 200, 25 JSON results, 0.8 s). Deleted the redundant `provider: "all"` (the `searchProvider: "searxng"` pin already wins in v0.22). Added `maxInlineContentChars: 50000`. Kept `workflow: "none"` and `ssrf.allowRanges: ["192.168.0.0/24"]`. +* **Docs**: `pi/packages/pi-web-access.md` bumped 0.14.0 → 0.22.0 (18-provider chain, config block, active-setup note, GitHub-clone section, yt-dlp present). `agentic-web-research/` SearXNG endpoint references repointed `.235` → `.143` (index, searxng-tuning, vpn-routing). +* **Note**: pi-web-access caches `web-search.json` in memory per process — the new endpoint takes effect on the next Pi session, not the running one. +* **Packages**: `yt-dlp` installed on dankware (2026.07.04) — YouTube frame extraction now works; `ffmpeg` (n9.0.1) was already present. + +## 2026-08-19 — SearXNG + Gluetun bring-up on dankclaw + +Field notes from standing up the search stack (gluetun + searxng + valkey) and confirming agentic JSON search. All four are operational; the SearXNG trio runs via podman-compose (not yet boot-persistent quadlet). + +* **Gluetun manual WireGuard**: a specific-server ProtonVPN config (private key + peer + endpoint) uses `VPN_SERVICE_PROVIDER=custom`, NOT `protonvpn`. The `protonvpn` provider is account/token-based and rejects a manually-set endpoint with `endpoint port is set`. Current Gluetun uses the single-peer model: `WIREGUARD_PUBLIC_KEY`, `WIREGUARD_ENDPOINT_IP`, `WIREGUARD_ENDPOINT_PORT`, `WIREGUARD_ADDRESSES` (not the old `WIREGUARD_PEERS_*` names). DNS is Gluetun's own `DNS_*` vars, not the WG `DNS` line. +* **Gluetun healthcheck**: the image has no `curl`, and its `:8000` status server 404s on every path. Use `test: ["CMD","sh","-c","test -e /sys/class/net/tun0"]` — tun0 exists only while the tunnel is connected. +* **SearXNG trusted group**: lives in `limiter.toml` (not `settings.yml`). A direct hit on the published port has no `X-Forwarded-For` header, so the bot-detection cannot resolve a client and returns 429 regardless of `pass_ip`. SearXNG must be reached through Caddy (which sets XFF); `trusted_proxies` then needs the podman bridge subnet (dynamic in rootless — pin the network CIDR) so Caddy's source is trusted for XFF extraction. +* **Rootless podman gotchas**: short image names do not resolve (no unqualified-search registries) — qualify with `docker.io/`. Binding privileged ports (Caddy 80/443) needs the one-time sysctl `net.ipv4.ip_unprivileged_port_start=80`. +* **Repo**: `serverAppConfigs` — added `shared/searxng/limiter.toml` + test seam, wired it into `deploy.sh`, fixed the Gluetun compose (peer env vars, qualified images, tun0 healthcheck), documented the rootless-port + Caddy/XFF gotchas, and skipped the ComfyUI GPU tests (migration pending). +* **Boot-persistence (quadlet)**: converted the trio from podman-compose to quadlet so it survives reboot. searxng sets `Network=gluetun.container` (reuses gluetun's netns → exits the tunnel); gluetun + valkey join a pinned `searxng.network` (10.89.2.0/24). Deployed via `scripts/deploy-searxng-quadlet.sh`. Field gotchas (also in `engineering/infra/containers.md`): the generator rejects `CapAdd=`/`Device=` (use `AddCapability=`/`AddDevice=`) and silently skips the unit; generated units cannot be `systemctl enable`d — `[Install] WantedBy=default.target` is the enablement (`is-enabled` = "generated"), and linger makes them boot-start. Verified: all three `is-enabled` = generated, tunnel up (US-WA), agentic JSON search returns 27 on-topic results. +* **open-webui moved to dankclaw (quadlet)**: the old open-webui was a bare container on Dankserver (:3000) pointing at a dead `:9090` backend. It now runs on Dankclaw as a boot-persistent quadlet (`scripts/deploy-open-webui-quadlet.sh`): CPU image `:main` (Dankclaw is CPU-only), isolated on `Network=slirp4netns`, published `:3005` (:3000 is Gitea's HTTP port), data at `/home/dank/Containers/open-webui/data`. Default LLM backend is the local vLLM (`host.containers.internal:52625`). The Dankserver `searxng` + `open-webui` bare containers were retired (data dirs preserved). `podman inspect <name>` can match an IMAGE, not just a container — a removed container still "exists" to inspect if its image remains; use `podman ps -a --filter name=` to check containers. +* **Model/port mapping corrected (live, 2026-08-19)**: the fleet endpoints are the REVERSE of the 2026-08-17 note. Live truth (probed `/v1/models`): `frank-default-large` is on **Dankclaw :52625** (vLLM, completion) and `frank-default-small` is on **Dankserver :7770** (llama.cpp FastMTP, completion+multimodal). The `serverAppConfigs` docs (Stack, OpenWebUI) were corrected; the sibling `vllmScripts` KB still carries the old mapping and should be updated there. +* **SearXNG 429 root cause (the "diva")**: the limiter's JSON cap is `API_MAX = 4` requests/IP/hour and that constant is **hardcoded in Python** (`searx/botdetection/ip_limit.py`), NOT settable in `limiter.toml`. The only bypass is `pass_ip` (SearXNG's `filter_request` returns before `ip_limit` runs when the IP is in `pass_ip`). Second gotcha: **rootless podman strips the client IP on published-port hits** — a request to the published port reaches the container with a slirp/bridge source (`10.88.x`/`10.89.x`), never the real client; only Caddy's `X-Forwarded-For` restores it. So even a LAN-IP curl 429'd. Fix: expand `pass_ip` to loopback (`127.0.0.1/32`, `::1`) + the host's private podman/slirp ranges (`10.88.0.0/16`, `10.89.0.0/16`) + the LAN. Verified: 20 concurrent JSON searches → all 200 (real results), while a spoofed public IP (8.8.8.8) still 429s (limiter still armed). The config file is root-owned (uid of the rootless podman namespace) — update with a one-off `sudo cp` + `systemctl --user restart searxng.service`. +* **ComfyUI GPU (gfx1151) — DONE (Option 1/B)**: the deferred GPU ComfyUI is now built and running. It was previously a bare CPU venv (`/home/dank/ComfyUI`, py3.14, `torch 2.13.0+cu130` with no NVIDIA → CPU fallback). Now it's a **container** `comfyui-rocm:gfx1151` built from `dankclaw/Containerfile.comfyui` on AMD's `rocm/vllm:rocm7.12.0_gfx1151_..._py3.12_pytorch_2.9.1` base (the only torch build where `torch.cuda.is_available()=True` on the Strix Halo APU). Key gotchas: (1) the base image already ships the ROCm torch/torchvision/torchaudio, so the Containerfile must **skip the torch family** from ComfyUI's `requirements.txt` (an unpinned `torch` would clobber the gfx1151 kernels) — filter with `grep -viE '^(torch|torchvision|torchaudio)([^a-z]|$)'`. (2) **rootless podman cannot `--group-add render`** (gid 990 is outside the subgid range 100000+); GPU access comes from the `/dev/kfd`+`/dev/dri` passthrough checked host-side (the run user is already in `render`), so add only the `video` group. Verified: `/system_stats` → `cuda:0 Radeon 8060S`, logs show `AMD arch: gfx1151` + active HIP backend. Boot-persistent via a user systemd unit running `podman compose up -d comfyui` (old venv unit saved as `comfyui.service.venv.bak`). The 4 `comfyui_rocm.bats` tests are un-skipped (the group test now asserts video present + render ABSENT). + +## 2026-08-17 — Fleet redo + vLLM tool calling + +* **Update**: `pi/models.md` — providers rewritten for the fleet redo: `llamacpp (dankserver)` at :7770 and `vllm (dankclaw)` at :52625; model selection strategy and live defaults brought in line with the new topology and the Quark W8A8 model. +* **Context**: the Frank fleet moved off the pipeline-parallel + NPU topology. `frank-default-large` (llama.cpp FastMTP, IQ4_XS) is on Dankserver; `frank-default-small` (vLLM ROCm, nameistoken Qwen3.6-35B-A3B Quark W8A8 INT8) is on Dankclaw with ngram spec and tool calling. The Avesed INT8 quant's tool-call XML fidelity was poor; the Quark quant follows the Qwen3 XML format cleanly. + + +## 2026-08-16 + +### Gitea Boot-Persistence Fix (dankclaw) + +* **Incident**: `unattended-upgrades` rebooted dankclaw at 15:01. The legacy podman-compose Gitea stack had no systemd units, so rootless podman did not auto-start the containers. Gitea was down ~1 hour. +* **Update**: `tools/gitea/index.md`, `architecture.md`, `management.md`, `data-persistence.md` — rewritten for the quadlet-managed stack: container/unit names, the `systemd-gitea` network (DNS-enabled), boot persistence (linger + `WantedBy=default.target`), the app.ini env-override gotcha, UID 100999 ownership, incident log. +* **Update**: `engineering/infra/containers.md` — marked `podman generate systemd` deprecated (podman 5.7), documented Quadlet with a field-tested gotcha list (default network DNS off, `[Service] EnvironmentFile=` for `${VAR}` expansion, unit naming, bind-mount UID mapping). + +## 2026-08-13 + +### Pi Subagents Limits + +* Added a "Parallel Execution and Limits" section to `pi/packages/pi-subagents.md`. +* Documented the effective values: `globalConcurrencyLimit` 2 (from `extensions/subagent/config.json`), `parallel.maxTasks` 8, `parallel.concurrency` 4, `maxSubagentSpawnsPerSession` unlimited, `maxSubagentDepth` 2, and `turnBudget.maxTurns` 30. +* Noted that no per-model limit exists; all caps are global to a run or a session. + +## 2026-08-11 (continued) + +### Engineering Research — New Area + +* Created the `engineering/` research area: SDLC and tooling, agent instruction files, language and framework stacks, infrastructure and cloud, pi plugins, skills ecosystem, and Signal remote control. +* Ran a parallel research fleet (scout + 6 researchers) grounded in current 2025/2026 web sources. + +### Skills Leaderboard — Live Verification + +* Queried the skills.sh API (`GET /api/skills/all-time/{page}`) for the authoritative top 50 skills by all-time installs. +* Replaced the inferred category table in `engineering/skills-ecosystem.md` with the verified ranked list. +* Noted the API’s zero-based pagination and 200-skill page size for future queries. + +## 2026-08-11 (continued) + +### Agentic Web Research — Grounded Revision + +* Ran a parallel research fleet (7 researchers + 2 scouts) for current 2025-2026 evidence on SearXNG tuning, VPN split-routing, agentic search, open models, research orchestration, and MCP. +* Rewrote all 8 `agentic-web-research/` pages to match verified facts and the local topology: SearXNG at `192.168.0.235:8081`, llama.cpp inference on `7770` (dankserver/dankclaw) and `8080` (local-ornith), main model `openrouter/deepseek-v4-flash-0731`. +* SearXNG: corrected to Valkey deployment, real engine defaults (DuckDuckGo/Wikipedia/Google News active, Google inactive, Bing disabled), limiter budgets, current `outgoing` defaults. +* VPN: added Gluetun as the recommended pattern, corrected OpenVPN container joins, added `source_ips`/`network: ipv4`. +* Open models: clarified Llama 4 claims (10M ctx = Scout only, single-H100 needs INT4, "beats GPT-4o" is Meta-only), added Qwen2.5-VL-7B as best self-hostable vision model. +* Web agents: corrected the Browser Use "87.4%" claim (managed Cloud variant, not open-source; peer-reviewed 44.5% for CUA), added Skyvern. +* MCP: updated transports (stdio + Streamable HTTP, legacy SSE), current reference servers, added SearXNG MCP, tightened security rules. + +### Exhaustive Bundle Audit + +* Link audit: resolved all 154+ wikilinks by frontmatter title — **0 broken wikilinks**. Fixed relative-link base errors in `core/index-doc.md`, `packages/index.md`, `pi-web-access.md`, `llama-cpp/setup.md`, `npx-skills/skill-commands.md`, `packages/pi-browser-use/index.md`. +* External URL audit: fixed dead links (SearXNG limiter path, earendil-works/pi blob URLs, AYayOS/qs -> outfoxxed/quickshell, badlogic/pi-mono -> earendil-works/pi). +* Factual fixes: `core/settings.md` stale JSON (defaultProvider/model/thinkingLevel/changelog-version), `pi/models.md` dankclaw auth, `Sleep-Fix-Guide.md` kernel 7.1.3 -> 7.1.4. +* Verified (did not change) `MemorySleepMode=deep`: it is a valid systemd 256+ option. +* ASD-STE100 style pass: removed contractions, banned `may`, and prose semicolons across research/tools/pi docs. +* Added OKF index frontmatter to `core/index.md` and `skills/index.md`. +* Added a "Pi-peon is installed" note to the npx skills ecosystem table and a port-7770 system note to llama.cpp docs. + +### Agentic Web Research Section + +* Created `agentic-web-research/` — seven new concept pages plus index covering self-hosted web agents, SearXNG tuning, VPN routing, agentic search practices, open models, research effectiveness, and model context protocol. +* Expanded via parallel research: concrete BM25/Pruning/LLM content filters, credibility heuristics, failure-mode guardrails, MCP server and transport guidance. +* Added the section to `index.md` under a new `## [Agentic Web Research]` heading. +* Linked `pi/packages/pi-web-access.md` to the new section. + +### System Instruction File + +* Created `AGENTS.md` — system behavior contract with a dedicated layer on parallel subagent execution (one `subagent` call with `tasks` + `concurrency`). + +### Bundle Audit + +* Verified all 154 wikilinks resolve (zero broken). +* Removed stale empty `Alienware M16a2 Sleep/Wake Issues.md` duplicate into `.AGENTTRASH`. +* ran ASD-STE100 style pass: converted `should` to imperative or `must`, and `e.g.` to `for example` across 10 files. +* Removed stale `frank-default-omni` model references and corrected dankclaw port `13305` to `8080` per commit `15d4af4`. +* **Resolved**: the live config is authoritative. Updated both llama.cpp servers to port `7770` and set the default provider to `openrouter` (deepseek) per `settings.json`. Dankserver/dankclaw now 7770; main session default is openrouter. + +## 2026-08-06 (continued) + +### Link Fixes + +* Fixed 15 broken wikilinks — added missing YAML frontmatter to `ghostty/index.md`, `tmux/index.md`, `linux-power-management/index.md`, `gitea/index.md`, `gitea/architecture.md`, `gitea/data-persistence.md`, `gitea/management.md` +* Fixed title mismatches: `OKF v0.1 Specification` → `Open Knowledge Format (OKF) v0.1 Specification`, `Pi Settings` → `Pi Settings System (settings.json)`, `Alienware M16a2 Sleep/Wake Issues` → `Alienware M16a2 Linux Sleep/Wake Issues`, `Architecture Details` → `Gitea Architecture`, `Data Persistence` → `Gitea Data Persistence`, `Management Guide` → `Gitea Management` +* Zero broken links remaining (47 links verified) + +## 2026-08-06 + +### ComfyUI Documentation + +* `tools/comfyui/index.md` — ComfyUI setup on dankclaw, architecture, service management +* `tools/comfyui/troubleshooting.md` — Common errors, diagnostics, recovery steps +* `tools/index.md` — Added ComfyUI entry +* `system/dankclaw.md` — Added ComfyUI service, hardware specs, services section + +### Major Documentation Overhaul + +**Created — System Documentation** + +* `system/index.md` — System documentation index with infrastructure diagram +* `system/dankware/index.md` — System overview for dankware (Alienware m16 R2) +* `system/dankware/hardware.md` — Complete hardware specifications +* `system/dankware/displays.md` — Three-monitor display configuration +* `system/dankware/network.md` — Network interfaces and topology +* `system/dankserver.md` — Primary llama.cpp server documentation +* `system/dankclaw.md` — Secondary llama.cpp server documentation + +**Created — Pi Configuration** + +* `pi/index.md` — Pi configuration overview with architecture diagram +* `pi/settings.md` — Main settings.json reference (moved from core/) +* `pi/models.md` — models.json provider and model definitions +* `pi/packages/index.md` — Installed packages index +* `pi/packages/pi-peon.md` — CESP/OpenPeon sound-pack player +* `pi/packages/pi-web-access.md` — Web search, fetching, video understanding +* `pi/packages/pi-subagents.md` — Core subagent delegation +* `pi/skills/index.md` — Installed agent skills inventory + +**Created — Tools** + +* `tools/cachyos/index.md` — CachyOS documentation (kernel, repos, gaming stack) +* `tools/noctalia-shell/index.md` — Noctalia Shell with Niri integration +* `tools/applications/index.md` — Default applications reference + +**Updated** + +* `core/settings.md` — Updated with current config, subagent overrides, cross-links +* `tools/niri/index.md` — Rewritten with actual system configuration +* `tools/index.md` — Added CachyOS, Noctalia, Applications entries +* `index.md` — Complete rewrite with new sections and cross-links + +**Moved / Cleaned** + +* `tmux.md` → `tools/tmux/index.md` +* Orphaned root duplicates → `.AGENTTRASH/` (npx-skills.md, okf-maintenance.md, okf-spec.md, vercel-labs-skills.md, vercel-labs-skills-find-skills.md, ornith-llama-cpp-setup.md) + +--- + +## 2026-07-18 + +* **Enhancement**: Expanded `okf-maintenance.md` — added cross-link management, index management, health metrics, troubleshooting, and quick reference card +* **Creation**: `core/log.md` — change log for the core documentation directory +* **Creation**: `.okf/config.yaml` — bundle tooling configuration +* **Update**: `core/index.md` — added log.md entry and cross-references + +## 2026-01-15 + +* **Initialization**: Converted docs bundle to OKF v0.1 format +* **Migration**: Migrated files to `core/`, `tools/`, `packages/`, `references/` directories +* **Applied**: OKF frontmatter to all files + +## 2025-08-05 — Gitea documentation + +Added ](tools/gitea/index.md) documentation to tools. Covers: + +* [[architecture|architecture]] — Container topology, Caddy reverse proxy, network diagram. +* [[management|management]] — Podman commands, upgrades, troubleshooting. +* [[data-persistence|data-persistence]] — Volume mounts, backup strategy, restore procedures. + +Updated tools index. diff --git a/omp-docs/packages/index.md b/omp-docs/packages/index.md new file mode 100644 index 0000000..d247e82 --- /dev/null +++ b/omp-docs/packages/index.md @@ -0,0 +1,15 @@ +# Pi Packages + +Self-contained extensions and tools bundled as npm packages, distributed via the `pi install` system. Each package contains extensions, skills, prompts, or themes. + +--- + +## Concept Files + +* [pi-browser-use](pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with `browser_` prefix, full config reference, session modes, and vision model setup. +* [pi-permission-system](pi-permission-system.md) — Permission enforcement and policy configuration system with 10 interconnected docs. + +## Cross-References + +- All packages are installed via `pi install npm:<name>` and loaded by pi's extension system. +- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution mechanism and package.json manifest format. diff --git a/omp-docs/packages/pi-browser-use.md b/omp-docs/packages/pi-browser-use.md new file mode 100644 index 0000000..09fe29a --- /dev/null +++ b/omp-docs/packages/pi-browser-use.md @@ -0,0 +1,117 @@ +--- +type: reference +title: Pi Browser Use +description: Browser automation extension wrapping chrome-devtools-mcp with a browser_ prefix for pi-coding-agent. +resource: https://github.com/TGYD-helige/pi +tags: + - pi + - package + - browser + - chrome-devtools-mcp + - unverified +timestamp: 2026-08-28 +--- +[pi-browser-use](https://github.com/TGYD-helige/pi) is a pi-coding-agent extension that wraps [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp), exposing all browser automation tools with a unified `browser_` prefix. + +**License:** Apache-2.0 + +--- + +## Features + +- **Dynamic tool discovery** — auto-proxies all upstream chrome-devtools-mcp tools with `browser_` prefix +- **Tool description augmentation** — adds usage hints for key tools +- **Result post-processing** — strips embedded snapshots, detects overlay/stale element issues +- **Optional visual analysis** — `browser_analyze_screenshot` via configurable vision model +- **Standalone mode** — runnable as independent MCP server via CLI + +### Requirements + +Node.js >= 20, Chrome (stable or newer), `@earendil-works/pi-coding-agent >= 0.74.0`. + +--- + +## Installation + +```bash +pi install npm:@amaster.ai/pi-browser-use +``` + +--- + +## Usage + +### As pi-coding-agent Extension (Recommended) + +Auto-discovers and loads on `session_start`. Configure in `.pi/settings.json`: + +```json +{ + "pi-browser-use": { + "headless": true, + "channel": "stable", + "viewport": "1280x720", + "experimentalVision": true + } +} +``` + +### As Standalone MCP Server + +```bash +npx @amaster.ai/pi-browser-use --headless --viewport=1280x720 +``` + +--- + +## Configuration + +### Session Mode + +| Mode | Description | +|------|-------------| +| `persistent` (default) | Reuses shared profile at `~/.pi/browser-profile` | +| `isolated` | Fresh ephemeral profile each session | +| `existing` | Connects to running browser instance | + +### Browser Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `headless` | `boolean` | `false` | Run headless | +| `channel` | `string` | — | Chrome channel: `canary`, `dev`, `beta`, `stable` | +| `viewport` | `string` | — | Viewport size, for example `1280x720` | +| `userDataDir` | `string` | — | Custom user data directory | + +### Vision Model + +```json +{ + "pi-browser-use": { + "visionModel": { + "provider": "openai", + "model": "gpt-4o" + } + } +} +``` + +Resolves API key and base URL from the model registry automatically. + +--- + +## Key Tools + +| Tool | Hint | +|------|------| +| `browser_click` | Use element uid from snapshot; UIDs invalidated after action | +| `browser_fill` | Does not work on canvas/custom widgets | +| `browser_press_key` | Accepts single key name only | +| `browser_take_snapshot` | Call first to get uids, and after every state-changing action | + +--- + +## Cross-References + +- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system. +- See [OKF Specification](../references/okf-spec.md) for the knowledge bundle format. diff --git a/omp-docs/packages/pi-permission-system.md b/omp-docs/packages/pi-permission-system.md new file mode 100644 index 0000000..2be3c11 --- /dev/null +++ b/omp-docs/packages/pi-permission-system.md @@ -0,0 +1,37 @@ +--- +type: reference +title: Pi Permission System +description: Permission enforcement and policy configuration system for pi-coding-agent extensions. +resource: https://github.com/gotgenes/pi-permission-system +tags: + - pi + - package + - permissions + - unverified +timestamp: 2026-08-28 +--- +[pi-permission-system](https://github.com/gotgenes/pi-permission-system) is the permission enforcement and policy configuration system for pi-coding-agent extensions. + +--- + +## Documentation Index + +| Document | File | Description | +|----------|------|-------------| +| Overview | README.md | Package overview, install, quick start, feature list | +| Configuration | configuration.md | Full policy reference, runtime knobs, per-agent overrides, common recipes | +| Session Approvals | session-approvals.md | Session-scoped rules, pattern suggestions, bash arity table | +| Cross-Extension API | cross-extension-api.md | Service accessor, event bus, decision/UI-prompt broadcasts | +| Subagent Integration | subagent-integration.md | Permission forwarding, coexistence with subagent extensions | +| Frontmatter Convention | permission-frontmatter-for-subagent-extensions.md | Convention guide for subagent extension authors | +| OpenCode Compatibility | opencode-compatibility.md | Shared concepts, divergences, porting guide | +| Troubleshooting | troubleshooting.md | Common issues, diagnostic logging, threat model | +| Migration: Legacy → Flat | legacy-to-flat.md | Migration from pre-v2 config layout | +| Migration: Strict Validation | strict-config-validation.md | Strict config validation (breaking) — reading and fixing rejected configs | + +--- + +## Cross-References + +- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system. +- See [AGENTS.md Format](../core/agents-md-format.md) for the system-level instruction format that governs how this system is referenced in agent contracts. diff --git a/omp-docs/pi/index.md b/omp-docs/pi/index.md new file mode 100644 index 0000000..c7b1072 --- /dev/null +++ b/omp-docs/pi/index.md @@ -0,0 +1,59 @@ +# Pi Configuration + +Documentation for the pi coding agent installation on ](../system/index.md). +Everything here is configured locally on `dankware`; the LLM providers are the +two llama.cpp servers (Dankserver, Dankclaw). + +## Configuration Files + +- [Pi Settings System (settings.json)](/core/settings.md) — Main `settings.json` reference. Providers, models, packages, subagent overrides. +- [Pi Models Configuration](/pi/models.md) — `models.json` reference. Provider definitions, model specs, endpoints. + +## Extensions + +- [Pi Packages](/pi/packages/index.md) — Installed npm packages that extend pi functionality. + - [Pi Peon](/pi/packages/pi-peon.md) — CESP/OpenPeon sound-pack player for lifecycle events. + - [Pi Web Access](/pi/packages/pi-web-access.md) — Web search, URL fetching, GitHub cloning, PDF extraction, video understanding. + - [Pi Browser Use](/packages/pi-browser-use.md) — Browser automation extension wrapping chrome-devtools-mcp with a `browser_` prefix. + - [Pi Permission System](/packages/pi-permission-system.md) — Permission enforcement and policy configuration for subagent extensions. + +## Skills + +- [Pi Skills](/pi/skills.md) — Installed agent skills. Symlinked from `~/.agents/skills/` and `~/.pi/agent/skills/`. + +## Subagent Architecture + +- [Pi Subagents](/pi/packages/pi-subagents.md) — Core subagent delegation system. Chains, parallel execution, TUI clarification. + +## Architecture + +```mermaid +graph TD + A[Pi TUI] --> B[settings.json] + A --> C[models.json] + B --> D[Default Provider: llamacpp] + B --> E[Default Model: frank-default-large] + B --> F[Packages] + B --> G[Subagent Overrides: local frank models] + F --> H[pi-peon] + F --> I[pi-web-access] + F --> J[pi-browser-use] + F --> K[pi-permission-system] + G --> L[Small: scout, researcher] + G --> M[Large: planner, worker, reviewer, oracle, context-builder] + L --> N[dankserver 192.168.0.235:7770] + M --> O[dankclaw 192.168.0.143:7770] +``` + +## Note on the Live Default + +`models.json` defines the live provider set. The main session provider is +`llamacpp`; the default model is `frank-default-large` (Dankclaw). Subagents +default to the local provider with `subagents.defaultModel = frank-default-small` +(Dankserver); larger roles map to `frank-default-large`. Two scopes own settings: +the user `~/.pi/settings.json` (main → Dankclaw/large) and the project +`/home/dank/.pi/agent/settings.json` (main → Dankserver/small). When the two +disagree, the project-scope `settings.json` in the agent home wins for the agent's +own main session; the user-scope file governs the interactive `pi` session. + +> **Note:** This documentation describes the pi-coding-agent era. The system has since migrated to the OMP harness era. Configuration is now at `~/.omp/agent/config.yml` and `~/.omp/agent/models.yml` (imported from `~/.pi/agent/models.json`). Legacy `~/.pi/settings.json` and `~/.pi/agent/settings.json` remain as pi-era artifacts. New OMP-managed skills live in `~/.omp/agent/managed-skills/` alongside the legacy symlinked skills at `~/.pi/agent/skills/` → `~/.agents/skills/`. diff --git a/omp-docs/pi/models.md b/omp-docs/pi/models.md new file mode 100644 index 0000000..dc4dcda --- /dev/null +++ b/omp-docs/pi/models.md @@ -0,0 +1,148 @@ +--- +type: reference +title: Pi Models Configuration +description: Complete reference for models.json — provider definitions, model specs, and API endpoints for the Frank Program. +tags: + - pi + - models + - providers + - llamacpp + - unverified +timestamp: 2026-08-28 +--- + +# Pi Models Configuration (`models.json`) + +`models.json` defines the LLM providers pi connects to. Each provider specifies a base URL, API type, authentication, and available models. + +**Location:** `/home/dank/.pi/agent/models.json` + +--- + +## Providers + +Current providers in `models.json` (verified 2026-08-27, after the +2026-08-18 service swap): + +### llamacpp (dankserver) + +| Property | Value | +|----------|-------| +| **Base URL** | `http://192.168.0.235:7770/v1` | +| **API** | `openai-completions` | +| **Auth** | None (EMPTY) | +| **Host** | [[dankserver|dankserver]] | + +#### Models + +| Model ID | Context Window | maxTokens | Reasoning | Input Types | +|----------|---------------|-----------|-----------|-------------| +| `frank-default-small` | 262,144 | 262,144 | Yes | Text, image | + +The server is upstream llama.cpp (b10121) serving HauhauCS +Qwen3.6-35B-A3B-Uncensored-Aggressive Q6_K_P with 36 MoE experts on CPU, +ngram-mod spec, 4 slots of ~175K context. The server serves the loaded +model regardless of the requested model ID. Requests with any `model` +value succeed. + +### llamacpp (dankclaw) + +| Property | Value | +|----------|-------| +| **Base URL** | `http://192.168.0.143:7770/v1` | +| **API** | `openai-completions` | +| **Auth** | None (EMPTY) | +| **Host** | [[dankclaw|dankclaw]] | + +> 2026-08-22: `frank-default-large` moved from `:52625` to `:7770` on +> Dankclaw (operator request: the primary inference server sits on the +> standard llama.cpp port). The OpenWebUI quadlet +> (`OPENAI_API_BASE_URL`) was re-pointed to `:7770` in the same change. + +#### Models + +| Model ID | Context Window | maxTokens | Reasoning | Input Types | +|----------|---------------|-----------|-----------|-------------| +| `frank-default-large` | 262,144 | 262,144 | Yes | Text, image | + +The server is the ROCmFPX llama.cpp runtime serving +[kingjones777's Qwen3.8-Flash-Next Uncensored ROCmFP4 STRIX_LEAN GGUF](https://huggingface.co/kingjones777/Qwen3.8-Flash-Next-Uncensored-ROCmFP4-STRIX_LEAN-GGUF) +— a 177B-parameter, 56B-MoE model sharded into 3 Q4_0-ROCmFP4 GGUF files +(98.3 GB total) with a standalone BF16 vision embedding project (0.85 GB). +Speculative decoding uses `--spec-type ngram-mod` because the ROCmFPX quantization +drops the 4B MTP head. The model is loaded from +`/home/dank/models/kingjones-Qwen3.8-Flash-Next-Uncensored-ROCmFP4-STRIX_LEAN/`; +the original Q4_0-ROCmFP4-STRIX variant remains as a `.backup` directory. +Context is 262144 (native max), 1 slot. Concurrent requests queue on the +single slot; the server never preempts a running generation. It exposes +`reasoning_content` in deepseek reasoning format and supports +multimodal (vision) inference via the embedded mmproj. + +2026-08-27: Upgraded from the original Qwen3.8-Flash-Next Q4_0-ROCmFP4-STRIX +GGUF to the Uncensored STRIX_LEAN variant with vision support and +ngram-mod speculative decoding. + +### Thinking Levels + +Pi's default thinking level is configured globally in `settings.json` as +`"defaultThinkingLevel": "medium"`. The model entries map Pi's `max` level to the llama.cpp-supported `xhigh` +wire value. Pi shows `max` in the thinking selector from the global settings, +but sends `reasoning_effort: "xhigh"` to both local llama.cpp endpoints. +`thinkingLevelMap` can translate a UI level without changing the global default. +Verified 2026-07-22: +`getSupportedThinkingLevels` returns `off,minimal,low,medium,high,xhigh` +and the live server accepts `reasoning_effort: "xhigh"` and returns +`reasoning_content` (verified 2026-08-21). + +Mechanism (pi-ai `models.js` + `openai-completions.js`): + +- `getSupportedThinkingLevels`: extended levels `xhigh`/`max` appear only + when `thinkingLevelMap` defines them (string = supported, `null` = + hidden, omitted = not supported). +- Default request path (no `compat.thinkingFormat`): sends + `reasoning_effort = thinkingLevelMap[level] ?? level` when + `supportsReasoningEffort` is true (default for this provider). + +## Token Budgets (`maxTokens`) + +Verified in the pi source, 2026-08-16 (`@earendil-works/pi-coding-agent` 0.84.1 + `pi-ai`): + +- `maxTokens` is an optional model field in `models.json`. When omitted, pi defaults the model object to 16,384 (`provider-composer.js`). +- The value is metadata. It drives the model-picker "max out" display and length-error recovery (`isRecoverableLength`). +- Normal chat turns do not send `max_tokens`. The request builder sends the field only when a per-request option is set (`openai-completions.js buildParams`: `if (options?.maxTokens)`). The agent loop passes no such option. +- The only pi calls that send `max_tokens` are context compaction and branch summarization. They are deliberately budgeted. + +## Model Selection Strategy + +```mermaid +graph LR + A[User Request] --> B{Complexity?} + B -->|Large context / long docs| C[frank-default-large<br/>CIRU llama.cpp dankclaw :7770, 262K ctx] + B -->|Fast / interactive| D[frank-default-small<br/>llama.cpp dankserver :7770, 262K ctx] + +The CIRU endpoint (dankclaw) serves the 177B 56B-MoE model with +262144 context, ngram-mod speculative decoding, 1 slot. Concurrent +requests queue on the single slot. The upstream +llama.cpp endpoint (dankserver) serves the 35B A3B MoE model with 36 +experts on CPU and 262K context per slot. +## Live Defaults + +`settings.json` picks the main session provider and model (verified 2026-08-19): + +| Scope | Provider | Model | +|-------|----------|-------| +| Main session | `llamacpp (dankclaw)` | `frank-default-large` | +| Subagent default | `frank-default-small` (llamacpp dankserver) | ~262K ctx per slot, ngram-mod spec | +| Subagent overrides | scout, researcher | `frank-default-small` | +| Subagent overrides | planner, worker, reviewer, oracle, context-builder | `frank-default-large` (llamacpp dankclaw) | + +The subagent model IDs (`frank-default-small`, `frank-default-large`) resolve against the new provider set in `models.json`. The current mappings are `max -> xhigh` for both local models; the global and subagent defaults remain `max`. + +--- + +## See Also + +- [[settings|settings]] — Main configuration file +- [[dankserver|dankserver]] — Primary llama.cpp server +- [[dankclaw|dankclaw]] — Secondary llama.cpp server +- [ornith-llama-cpp-setup](../tools/ornith-llama-cpp-setup/index.md) — Local Ornith model setup diff --git a/omp-docs/pi/packages/index.md b/omp-docs/pi/packages/index.md new file mode 100644 index 0000000..a27c256 --- /dev/null +++ b/omp-docs/pi/packages/index.md @@ -0,0 +1,29 @@ +# Pi Packages + +Pi extends its functionality through npm packages installed via `pi install`. Each package provides extensions, skills, prompts, or themes. + +## Installed Packages + +| Package | Version | Description | +|---------|---------|-------------| +| [[pi-peon|pi-peon]] | 0.1.1 | CESP/OpenPeon sound-pack player for pi lifecycle events | +| [[pi-web-access|pi-web-access]] | 0.22.0 | Web search, URL fetching, GitHub cloning, PDF extraction, video understanding | + +## Core Extension + +| Package | Version | Description | +|---------|---------|-------------| +| [[pi-subagents|pi-subagents]] | 0.36.0 | Core subagent delegation — chains, parallel execution, TUI clarification | + +--- + +## See Also + +- [[settings|settings]] — Package configuration in settings.json +- [pi](../index.md) — Pi configuration overview + + * [Pi Peon](pi-peon.md) — CESP/OpenPeon sound-pack player for pi lifecycle events — peons, GLaDOS, battlecruisers, and 300+ community sound packs. + + * [Pi Subagents](pi-subagents.md) — Core pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. + + * [Pi Web Access](pi-web-access.md) — Web search, URL fetching, GitHub cloning, PDF extraction, and video understanding for Pi. Zero-config with Exa MCP. diff --git a/omp-docs/pi/packages/pi-peon.md b/omp-docs/pi/packages/pi-peon.md new file mode 100644 index 0000000..d86e4b5 --- /dev/null +++ b/omp-docs/pi/packages/pi-peon.md @@ -0,0 +1,85 @@ +--- +type: reference +title: Pi Peon +description: CESP/OpenPeon sound-pack player for pi lifecycle events — peons, GLaDOS, battlecruisers, and 300+ community sound packs. +tags: + - pi + - package + - sound + - peon + - cesp + - openpeon + - unverified +timestamp: 2026-08-28 +--- + +# Pi Peon + +**Package:** `@wierdbytes/pi-peon` +**Version:** 0.1.1 +**Author:** wierdbytes + +Plays CESP/OpenPeon sound packs on pi lifecycle events. Drop a sound pack into `~/.openpeon/packs/<name>/` or install from the community registry (300+ packs). + +--- + +## Install + +```bash +pi install @wierdbytes/pi-peon +``` + +## Sound Packs + +Installed packs in `~/.openpeon/packs/`: + +| Pack | Theme | +|------|-------| +| `peon` | Warcraft III Orc Peon (default) | +| `peasant` | Medieval peasant | +| `sc2_scv` | StarCraft II SCV | +| `ra2_soviet_engineer` | Red Alert 2 Soviet Engineer | +| `sc_battlecruiser` | StarCraft Battlecruiser | +| `zugzug` | Zugzug robot | + +## Events + +| pi Event | CESP Category | +|----------|---------------| +| `session_start` | `session.start` | +| `agent_start` | `task.acknowledge` | +| `agent_end` (used tools) | `task.complete` | +| `agent_end` (no tools) | `input.required` | +| `tool_result` (error) | `task.error` | +| Rate limit (429) | `resource.limit` | +| `task.progress` | `task.progress` | +| User spam (3 msgs/5s) | `user.spam` | + +## Commands + +| Command | Description | +|---------|-------------| +| `/peon` | Open settings modal | +| `/peon status` | Print active pack + config | +| `/peon mute` | Silence all categories | +| `/peon unmute` | Re-enable sounds | +| `/peon test [category]` | Play a random sound | +| `/peon reset` | Restore default config | + +CLI flag `--no-peon` disables playback for one session. + +## Settings + +The `/peon` command opens an interactive settings modal with: + +- **Packs** — Active, available, and registry packs +- **Volume** — Global volume control +- **Mute** — Per-event toggles +- **Registry browser** — Browse and install from community registry + +--- + +## See Also + +- [packages](../../packages/index.md) — Package overview +- [pi](../index.md) — Pi configuration diff --git a/omp-docs/pi/packages/pi-subagents.md b/omp-docs/pi/packages/pi-subagents.md new file mode 100644 index 0000000..7914a54 --- /dev/null +++ b/omp-docs/pi/packages/pi-subagents.md @@ -0,0 +1,68 @@ +--- +type: reference +title: Pi Subagents +description: Core pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. +tags: + - pi + - subagents + - delegation + - chains + - limits + - unverified +timestamp: 2026-08-28 +--- + +# Pi Subagents + +**Package:** `pi-subagents` +**Version:** 0.36.0 + +Core pi extension for delegating tasks to subagents. Supports sequential chains, parallel execution, and TUI clarification workflows. + +## Features + +- **Sequential chains** — Pipeline tasks through multiple subagents +- **Parallel execution** — Fan out independent tasks simultaneously +- **TUI clarification** — Interactive preview and editing before execution +- **Watchdog** — Health monitoring for subagent runs +- **Model overrides** — Per-agent model selection + +## Agent Roles + +| Role | Default Model | Purpose | +|------|---------------|---------| +| `scout` | frank-default-small | Quick exploration | +| `researcher` | frank-default-small | Information gathering | +| `planner` | frank-default-large | Task planning | +| `worker` | frank-default-large | Implementation | +| `reviewer` | frank-default-large | Code/document review | +| `oracle` | frank-default-large | Complex reasoning | +| `context-builder` | frank-default-large | Context building | + +## Parallel Execution and Limits + +Parallel execution fans out independent tasks. The extension applies several limits to control the load. + +| Limit | Effective value | Source | +|-------|-----------------|--------| +| `globalConcurrencyLimit` | **2** | `extensions/subagent/config.json` | +| `parallel.maxTasks` | 8 | default | +| `parallel.concurrency` | 4 | default | +| `maxSubagentSpawnsPerSession` | unlimited | default | +| `maxSubagentDepth` | 2 | default | +| `turnBudget.maxTurns` | 30 | `extensions/subagent/config.json` | + +`globalConcurrencyLimit` caps the simultaneously-running subagent tasks within one run. The default is 20. The value here is 2. Effective concurrency is the lower of the local cap and the available global slots. Per-step `concurrency` and `parallel.concurrency` still apply. A value below 1 is clamped to 1. + +Set `globalConcurrencyLimit` in `extensions/subagent/config.json`. The file also configures `artifactDir`, `turnBudget`, and proactive skill suggestions. + +`maxSubagentSpawnsPerSession` caps the cumulative child launches during one parent session. It counts completed and failed children, parallel task counts, static chain steps, and bounded dynamic fanout children. The default is unlimited. Set the value to `0` to disable a configured cap. + +`maxSubagentDepth` controls nested delegation. The default is 2. Each agent can tighten the limit for its own child runs. An agent cannot relax a stricter inherited limit. + +No per-model limit exists. All caps are global to a run or a session. They do not depend on the child model. + +## See Also + +- [[settings|settings]] — Subagent configuration +- [[models|models]] — Model definitions diff --git a/omp-docs/pi/packages/pi-web-access.md b/omp-docs/pi/packages/pi-web-access.md new file mode 100644 index 0000000..a0064a8 --- /dev/null +++ b/omp-docs/pi/packages/pi-web-access.md @@ -0,0 +1,141 @@ +--- +type: reference +title: Pi Web Access +description: Web search, URL fetching, GitHub cloning, PDF extraction, and video understanding for Pi. Zero-config with Exa MCP. +tags: + - pi + - package + - web-search + - fetch + - youtube + - unverified +timestamp: 2026-08-28 +--- + +# Pi Web Access + +**Package:** `pi-web-access` +**Version:** 0.22.0 +**Author:** Nico Bailon + +Web search, content extraction, and video understanding for Pi. It calls your self-hosted SearXNG first when one is configured, and falls through to other providers. + +> **Active setup:** `~/.pi/web-search.json` locks search to SearXNG at `http://192.168.0.143:8081` (dankclaw), permits LAN fetches via `ssrf.allowRanges`, and sets `maxInlineContentChars` to 50000. The config file is cached in memory per process — a changed file takes effect on the next Pi session. + +--- + +## Install + +```bash +pi install npm:pi-web-access +``` + +## Search Providers + +Provider chain (in priority order, v0.22): + +1. **SearXNG** (if configured) — Self-hosted, private search +2. **OpenAI** — Codex subscription or API key +3. **Exa** — Zero-config via MCP, or API key +4. **Brave** — API key +5. **Parallel** — API key +6. **TinyFish** — API key +7. **Search1API** — API key +8. **Searchinfinity** — API key +9. **Querit** — API key +10. **Tavily** — API key +11. **Jina** — API key +12. **SERPdive** — API key +13. **Kagi** — API key +14. **Bocha** — API key +15. **Ollama** — API key +16. **Perplexity** — API key +17. **Gemini API** — API key +18. **Gemini Web** — Browser-cookie access + +A single-provider field (`provider` or `searchProvider`) pins the default and takes precedence over `searchRouting`. `searchRouting.providers` plus `fallbackOn` define an explicit ordered fallback over typed failures (`transient`, `quota`, `network`, `invalid-response`). + +## Configuration + +**Location:** `~/.pi/web-search.json` + +```json +{ + "searxngBaseUrl": "http://192.168.0.143:8081", + "searchProvider": "searxng", + "maxInlineContentChars": 50000, + "workflow": "none", + "ssrf": { + "allowRanges": ["192.168.0.0/24"] + }, + "openaiApiKey": "sk-...", + "braveApiKey": "BSA_...", + "exaApiKey": "exa-...", + "perplexityApiKey": "pplx-...", + "geminiApiKey": "AIza..." +} +``` + +Key fields: + +- `searxngBaseUrl` — the SearXNG instance to call. Env `SEARXNG_BASE_URL` wins over this file. The client calls `GET {base}/search?q=...&format=json` with a 30 s timeout; the base URL and its redirects stay subject to the SSRF guard. +- `searchProvider` — `searxng` locks the primary provider. `auto` picks the first available. A single-provider field wins over `searchRouting`. +- `maxInlineContentChars` — size of each `fetch_content` / `get_search_content` content slice. Default 30000, cap 200000. Full fetched content stays stored for later retrieval. +- `ssrf.allowRanges` — LAN CIDR ranges allowed through `fetch_content`. This blocks private IPs by default. +- `workflow` — `none` (raw results, no browser), `summary-review` (curator window with summary draft), or `auto-summary`. + +## Capabilities + +### Web Search + +```typescript +web_search({ query: "TypeScript best practices 2025" }) +``` + +### URL Fetching + +```typescript +fetch_content({ url: "https://docs.example.com/guide" }) +``` + +### GitHub Cloning + +GitHub URLs are cloned locally. The agent gets real file contents, not rendered HTML. + +```typescript +fetch_content({ url: "https://github.com/owner/repo" }) +``` + +### Video Understanding + +Point at a YouTube video or local screen recording and ask questions about visual content. + +```typescript +// YouTube +fetch_content({ url: "https://youtube.com/watch?v=...", prompt: "What book is shown?" }) + +// Local video +fetch_content({ url: "/path/to/recording.mp4" }) +``` + +### PDF Extraction + +```typescript +fetch_content({ url: "https://example.com/paper.pdf" }) +``` + +## Optional Dependencies + +```bash +# Video frame extraction +sudo pacman -S ffmpeg yt-dlp +``` + +Without these, video analysis (transcripts, visual descriptions via Gemini) still works. Frame extraction requires ffmpeg and yt-dlp. Both are installed on dankware (verified 2026-08-28: ffmpeg n9.0.1, yt-dlp 2026.08.19). + +GitHub URLs get special handling: `fetch_content` clones the repo locally instead of scraping HTML (root URL returns tree + README, `/blob/` returns file contents). Repos over 350 MB get an API-based view; `forceClone: true` overrides. Clones cache per session under `/tmp/pi-github-repos` and wipe on session change. Private repos need the `gh` CLI. Disable with `githubClone.enabled: false`. + +## See Also + +- [Pi Packages](index.md) — Package overview +- [Pi Configuration](../index.md) — Pi configuration diff --git a/omp-docs/pi/skills.md b/omp-docs/pi/skills.md new file mode 100644 index 0000000..e5631d0 --- /dev/null +++ b/omp-docs/pi/skills.md @@ -0,0 +1,47 @@ +--- +type: index +title: Pi Skills +description: Documentation for installed agent skills — code-review, diagnosing-bugs, find-skills, grilling, handoff, implement, obsidian-vault, prototype, tdd, teach, writing-great-skills, writing-guidelines, and zim-knowledge-base. +tags: + - pi + - skills + - index + - unverified +timestamp: 2026-08-28 +--- + +# Pi Skills + +Agent skills teach the agent new workflows. Skills are stored in `~/.pi/agent/skills/` (local) and symlinked from `~/.agents/skills/`. + +## Installed Skills + +| Skill | Source | Description | +|-------|--------|-------------| +| **code-review** | Local | Two-axis review: Standards and Spec, parallel sub-agents | +| **diagnosing-bugs** | Symlinked (.agents) | Diagnosis loop for hard bugs and performance regressions | +| **find-skills** | Symlinked (.agents) | Discover and install agent skills from the ecosystem | +| **grilling** | Symlinked (.agents) | Stress-test a plan or design before building | +| **handoff** | Local | Compact conversation into a handoff document | +| **implement** | Symlinked (.agents) | Implement work from specs or tickets | +| **obsidian-vault** | Symlinked (.agents) | Search, create, manage notes in Obsidian vault | +| **prototype** | Symlinked (.agents) | Build throwaway prototypes for design questions | +| **tdd** | Symlinked (.agents) | Test-driven development, red-green-refactor | +| **teach** | Symlinked (.agents) | Teach the user a new skill or concept | +| **writing-great-skills** | Symlinked (.agents) | Reference for writing and editing agent skills well | +| **writing-guidelines** | Local | Review docs for Writing Guidelines compliance | +| **zim-knowledge-base** | Local | Search Wikipedia ZIM files for research | + +## Skill Locations + +| Path | Type | +|------|------| +| `~/.pi/agent/skills/` | Local skills directory | +| `~/.agents/skills/` | Shared skills (symlinked from) | + +--- + +## See Also + +- [pi](index.md) — Pi configuration overview +- [[npx-skills|npx-skills]] — Skill distribution via npm diff --git a/omp-docs/references/index.md b/omp-docs/references/index.md new file mode 100644 index 0000000..ed47a93 --- /dev/null +++ b/omp-docs/references/index.md @@ -0,0 +1,10 @@ +# Reference Material + +Keep your OKF knowledge bundle from rotting — change tracking, frontmatter discipline, staleness detection, and automation. + +## Concept Files + +| File | Type | Description | +|------|------|-------------| +| [okf-maintenance.md](okf-maintenance.md) | guide | Keep your OKF knowledge bundle from rotting — change tracking, frontmatter discipline, staleness detection, and automation. | +| [okf-spec.md](okf-spec.md) | reference | Complete specification for OKF knowledge bundles — a directory of markdown files with YAML frontmatter. | diff --git a/omp-docs/references/okf-maintenance.md b/omp-docs/references/okf-maintenance.md new file mode 100644 index 0000000..900f5e8 --- /dev/null +++ b/omp-docs/references/okf-maintenance.md @@ -0,0 +1,147 @@ +--- +type: guide +title: OKF Bundle Maintenance +description: Keep your OKF knowledge bundle from rotting — change tracking, frontmatter discipline, staleness detection, and automation. +tags: + - okf + - maintenance + - documentation + - best-practices + - unverified +timestamp: 2026-01-15 +--- + +# OKF Bundle Maintenance + +Knowledge bundles rot. It is the nature of knowledge to attract cobwebs, much like an unvisited pantry attracts spiders that are frankly doing you a favor by reminding you it has been a while. An OKF bundle maintained by agents is no exception — files drift out of sync, frontmatter becomes decorative, and `index.md` turns into a ghost town where links go to die. + +**The core principle:** if you do not track changes, you do not know when they happened. If you do not have a changelog, you are the person who finds the broken thermostat and wonders why it is set to "volcano." + +--- + +## Change Tracking with `log.md` + +Every OKF bundle has a `log.md` file. It is not optional. It is the bundle's memory. + +**Format:** Date-grouped entries, newest first. One line per change with timestamp, file path, and what changed. + +```markdown +# Bundle Change Log + +## 2026-01-15 +- `/docs/ghostty.md` — Updated keybind table after v1.2 release +- `/docs/pi-permission-system/` — Added `policy.md` and `audit.md` +- `/docs/index.md` — Synced with directory contents +``` + +**Rules:** +- **Newest entries first.** Putting old entries at the top inverts the timeline and makes it impossible to see what just happened. +- **One line per change.** A single line is sufficient. The git history is there if someone wants the gory details. +- **Group by date.** Batch all changes from the same day together. +- **Always date-stamp the section.** Use `## YYYY-MM-DD`. +- **Mention `index.md` whenever you change a bundle.** If you added or removed a file, update the index and note it in the log. + +### Common Mistakes + +- ❌ Writing `"Updated ghostty.md"` — Updated it with what? Be specific. +- ❌ Forgetting to write to `log.md` — This is the equivalent of doing surgery without keeping a record. +- ❌ Using relative paths — Use absolute paths (`/docs/ghostty.md`). +- ❌ Leaving stale entries from manual edits — The log is the single source of truth. + +--- + +## Frontmatter Discipline + +Frontmatter is the metadata layer. It is not decoration. + +### Required field: +- `type` — The concept type. The only strictly required frontmatter field. + +### Strongly recommended: +- `description` — The preview text. Without it, the file is invisible and confusing. +- `tags` — Use for cross-cutting concerns. Tags hold things together across categories. +- `timestamp` — Include for staleness detection. A file with a timestamp from 2023 is more likely stale than one from 2026. +- `title` — Optional but helpful. + +### Rules: +- ✅ Every concept file must have a `description`. +- ✅ Use `tags` liberally but consistently. +- ✅ Include `timestamp` on every file. +- ✅ Pick descriptive `type` values: `reference`, `guide`, `configuration`, `tutorial`. +- ❌ Don't use `type: file` or `type: document` — be specific. +- ❌ Never leave `description` blank or copy the title. + +--- + +## One Thing Per File + +OKF is built on the principle that a file is one concept. + +**Splitting criteria:** +- ✅ One topic, one file. If the content can be summarized in one sentence without using "and," it belongs in one file. +- ✅ Give each file its own `type`. +- ✅ Keep each file between 1 and 500 lines. Under 1 = over-split. Over 500 = under-split. +- ❌ Don't create a file called `misc.md` — `misc` is a graveyard, not a category. +- ❌ Don't use `# Other` or `# Additional Notes` sections — these are taping things to the wall. + +--- + +## Auto-Generation Strategies + +### Index files as living documents: + +```bash +find docs/bundle-name/ -name '*.md' ! -name 'log.md' -type f | \ + sort | \ + awk '{print "- " $0}' > docs/bundle-name/index.md +``` + +### Staleness detection: + +```bash +# Find files older than 90 days +find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \ + -mtime +90 -type f -print + +# Find files missing timestamp +find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \ + -type f -exec grep -L '^timestamp:' {} \; + +# Find files missing description +find docs/ -name '*.md' ! -name 'index.md' ! -name 'log.md' \ + -type f -exec grep -L '^description:' {} \; +``` + +--- + +## Version Control Best Practices + +- ✅ One logical change per commit +- ✅ Write meaningful commit messages ("Updated file" is not a commit message. It is a shrug in text form.) +- ❌ Don't commit entire bundle dumps — a commit touching 50 files is a data dump, not a change + +### Useful git commands: + +```bash +git blame -L 1,30 docs/ghostty.md # Who changed what and when +git log --oneline -n 10 -- docs/pi-permission-system/ # Last commits in a directory +git status --short # What is uncommitted +``` + +--- + +## Knowing When Something Is Stale + +| Signal | Threshold | Action | +|--------|-----------|--------| +| `timestamp` field older than 6 months | Auto-flag | Review and update or archive | +| File not modified in 12 months | Auto-flag | Assess whether still relevant | +| `index.md` count differs from file count | Always | Fix immediately | +| `log.md` has no entries for 30+ days | Context-dependent | Normal if no changes made | + +--- + +## See Also + +- [OKF v0.1 Specification](okf-spec.md) — The complete format specification. +- [Root Index](/index.md) — This bundle's structure and navigation. diff --git a/omp-docs/references/okf-spec.md b/omp-docs/references/okf-spec.md new file mode 100644 index 0000000..0b032d5 --- /dev/null +++ b/omp-docs/references/okf-spec.md @@ -0,0 +1,154 @@ +--- +type: reference +title: Open Knowledge Format (OKF) v0.1 Specification +description: Complete specification for OKF knowledge bundles — a directory of markdown files with YAML frontmatter. +resource: https://github.com/GoogleCloudPlatform/open-knowledge-format +tags: + - okf + - documentation + - knowledge-bundle + - specification +verified: 2026-08-28 +timestamp: 2026-01-15 +--- + +> **Note:** Google Cloud published OKF v0.2 at [GoogleCloudPlatform/open-knowledge-format](https://github.com/GoogleCloudPlatform/open-knowledge-format) with additional frontmatter families for provenance, trust, and attestation. This document covers the v0.1 format used by this knowledge bundle. + +# Open Knowledge Format (OKF) v0.1 + +OKF is the answer to "everyone has knowledge, but nobody speaks the same language." Every agent, catalog, wiki, and metadata store represents knowledge differently — and every agent builder is reinventing the context-assembly wheel. + +OKF v0.1 formalizes the "LLM wiki" pattern into a portable, interoperable format. The entire specification is simple enough to fit on a single page: + +> **A directory of markdown files with YAML frontmatter.** + +That's it. No schema registry. No central authority. No SDK. No runtime. If you can `cat` a file, you can read OKF. If you can `git clone` a repo, you can ship it. + +--- + +## What's in a Bundle? + +An OKF knowledge bundle is a directory tree. Every concept is one file. The file path is the concept's identity. + +``` +my-bundle/ +├── index.md # Optional directory listing +├── log.md # Optional update history +├── concept-one.md # A concept at the root level +└── subdirectory/ + ├── index.md # Optional subdirectory listing + ├── concept-two.md # A concept in a subdirectory + └── another-concept.md # Another concept +``` + +**Reserved filenames** (MUST NOT use for concepts): + +| Filename | Purpose | +|----------|---------| +| `index.md` | Directory listing for progressive disclosure | +| `log.md` | Chronological update history | + +--- + +## Anatomy of a Concept Document + +```yaml +--- +type: <Type name> # REQUIRED +title: <Optional display name> +description: <Optional one-line summary> +resource: <Optional canonical URI> +tags: [<tag>, <tag>, …] # Optional +timestamp: <ISO 8601 datetime> # Optional +--- +``` + +### Required Fields + +| Field | Required? | What it does | +|-------|-----------|-------------| +| `type` | **Yes** | Identifies the kind of concept. Used for routing, filtering, presentation. | +| `title` | No | Human-readable display name. | +| `description` | No | Single-sentence summary. Used by index generators, search snippets, previews. | +| `resource` | No | URI identifying the underlying asset. | +| `tags` | No | YAML list for cross-cutting categorization. | +| `timestamp` | No | ISO 8601 datetime of last meaningful change. | + +--- + +## Index Files — Progressive Disclosure + +An `index.md` in any directory lets a human or agent see what's available: + +```markdown +# Sales Tables + +* [Orders](tables/orders.md) - One row per completed customer order. +* [Customers](tables/customers.md) - Customer account information. +``` + +**Rules:** No frontmatter. Relative paths. One section per heading. Entries include description from linked concept's frontmatter. + +--- + +## Log Files — Change History + +```markdown +# Directory Update Log + +## 2026-05-22 +* **Update**: Added new reference for [Customer Metrics](/tables/customer-metrics.md). +* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md). +``` + +- Date headings MUST use `YYYY-MM-DD` +- Entries grouped newest-first +- Leading bold word is a convention, not a requirement + +--- + +## Cross-linking + +**Absolute (bundle-relative) links — RECOMMENDED:** + +```markdown +See the [customers table](/tables/customers.md) for the join key. +``` + +**Relative links:** + +```markdown +See the [neighboring concept](./other.md). +``` + +Consumers MUST tolerate broken links. + +--- + +## Conformance Rules + +A bundle is **conformant** with OKF v0.1 if and only if: + +1. **Every non-reserved `.md` file** contains a parseable YAML frontmatter block. +2. **Every frontmatter block** contains a non-empty `type` field. +3. **Every reserved filename** follows the structure described here when present. + +Everything else is soft guidance. Consumers MUST NOT reject a bundle because of missing optional fields, unknown types, or broken links. + +--- + +## Common Mistakes + +- ❌ Forgetting the `type` field — this is the only strictly required field +- ❌ Using `type: file` or `type: document` — be specific: `type: BigQuery Table`, `type: API Endpoint` +- ❌ Putting frontmatter in `index.md` — index files are directory listings, not concepts +- ❌ Using relative links for concepts in different directories — use absolute paths +- ❌ Writing one giant `index.md` that lists everything — use `index.md` at multiple levels +- ❌ Skipping `# Citations` for factual claims — cite external sources under `# Citations` + +--- + +## See Also + +- [OKF Bundle Maintenance](okf-maintenance.md) — How to keep your bundle from rotting. +- [Root Index](/index.md) — This bundle's structure and navigation. diff --git a/omp-docs/reports/sleep-wake-investigation-report.html b/omp-docs/reports/sleep-wake-investigation-report.html new file mode 100644 index 0000000..8afae3e --- /dev/null +++ b/omp-docs/reports/sleep-wake-investigation-report.html @@ -0,0 +1,830 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>Alienware M16 R2 Sleep/Wake Issue Report + + + +
+

Sleep/Wake Issue Investigation Report

+

Alienware M16 R2 • CachyOS (Kernel 7.1.4) • NVIDIA RTX 4070

+

Generated: July 22, 2026

+
+ +
+ +
+

OverviewExecutive Summary

+ +
+
+

Sleep State

+
s2idle only
+
+
+

GPU Driver

+
Notifiers enabled
+
+
+

NVIDIA Services

+
Enabled
+
+
+

ACPI Issues

+
Multiple errors
+
+
+ +

Problem Description

+

Your machine enters sleep when closing the lid, but exhibits issues properly waking from sleep. The screen may remain black, or the system may exhibit partial wake behavior.

+ +
+

🔴 Root Cause Identified

+

The primary issue is that the system only supports s2idle (Modern Standby) sleep state, which is fundamentally broken for NVIDIA hybrid GPU configurations on Linux. Deep S3 sleep is available but not enabled by default.

+
+
+ + +
+

HardwareSystem Configuration

+ +

Hardware Specifications

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyValue
MachineAlienware m16 R2 (Model 01HV0T)
BIOSv1.15.0 (08/06/2025)
CPUIntel Core Ultra 7 155H (Meteor Lake-H)
GPUNVIDIA RTX 4070 Max-Q (PRIME hybrid)
Kernel7.1.4-1-cachyos
Display ManagerSDDM with niri Wayland compositor
+ +

Current Power Settings

+ 
/sys/power/mem_sleep: [s2idle]      ← ONLY s2idle available
+/sys/power/state:    freeze mem disk
+NVIDIA Driver: 610.43.03 (proprietary)
+PreserveVideoMemoryAllocations: 2    ← Enabled
+UseKernelSuspendNotifiers: 1        ← Enabled
+
+ + +
+

DiagnosisIdentified Issues

+ +

Primary Issues

+ + +

Kernel Error Logs

+ 
Jul 22 19:43:43 dankware kernel: NVRM: RmHandleDNotifierEvent: Failed to handle ACPI D-Notifier event, status=0x11
+Jul 22 19:43:43 dankware kernel: spd5118 18-0050: PM: dpm_run_callback(): spd5118_resume [spd5118] returns -6
+Jul 22 19:43:43 dankware kernel: spd5118 18-0050: PM: failed to resume async: error -6
+Jul 22 19:49:48 cachyos kernel: ACPI BIOS Error (bug): Could not resolve symbol [\_SB.PC00.XHCI.RHUB.SS03], AE_NOT_FOUND
+Jul 22 19:50:08 dankware kernel: i915 0000:00:02.0: [drm] *ERROR* GT1: GSC proxy component didn't bind within expected timeout
+
+ + +
+

HistoryPrevious Work Completed

+ +

Documentation Created

+
+
+
July 9, 2026
+
Diagnostic script created
+
/home/dank/.pi/scripts/diagnose-sleep-wake.sh — 700+ line comprehensive diagnostic tool
+
+
+
July 18, 2026
+
Research documentation written
+
Alienware-M16a2-Linux-sleep-wake-issues.md (424 lines) and Sleep-Fix-Guide.md (260 lines)
+
+
+
July 20, 2026
+
Repository reorganized
+
Split documentation into docs/research/ and docs/tools/ directories with proper OKF structure
+
+
+ +

Files Created

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FilePurposeStatus
scripts/diagnose-sleep-wake.shComprehensive diagnostic toolReady to run
docs/research/Alienware-M16a2-Linux-sleep-wake-issues.mdRoot cause researchComplete
docs/research/Sleep-Fix-Guide.mdStep-by-step fix implementation guideComplete
docs/tools/linux-power-management/index.mdConfiguration referenceComplete
+ +

What Has Been Done

+
+

📚 Extensive Research Completed

+

Comprehensive research was conducted on NVIDIA GPU driver state corruption during suspend/resume, documenting 10+ GitHub issues from the NVIDIA/open-gpu-kernel-modules repository, identifying patterns across Dell/Alienware systems, and tracking kernel regressions affecting s2idle with NVIDIA hybrid GPUs.

+
+ +

What Has NOT Been Done

+
+

⚠️ None of the documented fixes have been applied yet

+

Despite comprehensive documentation and research, the actual system configuration changes remain pending.

+
+
+ + +
+

SolutionRecommended Fixes

+ +

Implementation Priority

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PriorityFixRationale
CRITICALForce S3 deep sleeps2idle is fundamentally broken for NVIDIA hybrid GPUs
HIGHBlacklist nvidiafb moduleKnown to cause black screen on resume
HIGHAdd kernel parametersImprove ACPI and sleep behavior
MEDIUMUpdate BIOS/firmwareDell frequently fixes ACPI/suspend bugs in updates
MEDIUMDisable problematic wake sources8 wake sources enabled, including XHCI (USB)
+ +

Detailed Fix Instructions

+ +

Fix #1: Force S3 Deep Sleep (CRITICAL)

+ 
# Check if S3 is supported
+cat /sys/power/mem_sleep
+# Current: [s2idle] — need to enable "deep"
+
+# Test S3 temporarily
+echo deep | sudo tee /sys/power/mem_sleep
+
+# If successful, make permanent by adding to bootloader:
+# GRUB: GRUB_CMDLINE_LINUX_DEFAULT="... mem_sleep_default=deep"
+# systemd-boot: Add "mem_sleep_default=deep" to options line
+ +

Fix #2: Blacklist nvidiafb Module

+ 
# Create blacklist file
+sudo tee /etc/modprobe.d/blacklist-nvidiafb.conf > /dev/null <<'EOF'
+blacklist nvidiafb
+EOF
+
+# Regenerate initramfs
+sudo mkinitcpio -P
+
+# Verify
+lsmod | grep -q nvidiafb && echo "FAIL" || echo "PASS"
+ +

Fix #3: Add Kernel Parameters

+ 
# Edit your bootloader config and add these parameters:
+mem_sleep_default=deep acpi_backlight=vendor acpi_enforce_resources=lax
+
+# For GRUB, edit /etc/default/grub:
+GRUB_CMDLINE_LINUX_DEFAULT="quiet splash mem_sleep_default=deep acpi_backlight=vendor acpi_enforce_resources=lax nvidia-drm.modeset=1 pcie_aspm=off"
+
+# Then update:
+sudo update-grub
+ +

Fix #4: Update BIOS/Firmware

+ 
# Check current version
+sudo dmidecode -s bios-version
+# Current: v1.15.0 (08/06/2025)
+
+# Check for updates
+sudo fwupdmgr get-updates
+sudo fwupdmgr update
+
+# Or download from Dell Support
+ +

Fix #5: Disable Problematic Wake Sources

+ 
# View current wake sources
+cat /proc/acpi/wakeup
+# XHCI, RP01, RP05, RP07, RP08, RP09, RP12 are enabled (8 total)
+
+# Toggle problematic devices (temporary - resets on reboot)
+sudo sh -c 'echo XHCI > /proc/acpi/wakeup'
+
+# For permanent fix, create systemd service:
+ 
sudo tee /etc/systemd/system/disable-wake-devices.service > /dev/null <<'EOF'
+[Unit]
+Description=Disable problematic wake devices
+Before=sleep.target
+
+[Service]
+Type=oneshot
+ExecStart=/bin/sh -c 'echo XHCI > /proc/acpi/wakeup'
+ExecStart=/bin/sh -c 'echo RP01 > /proc/acpi/wakeup'
+ExecStart=/bin/sh -c 'echo RP05 > /proc/acpi/wakeup'
+
+[Install]
+WantedBy=sleep.target
+EOF
+
+sudo systemctl enable disable-wake-devices.service
+
+ + +
+

VerifyTesting Procedure

+ +

Test After Each Fix

+
    +
  1. Manual Suspend: systemctl suspend — System should sleep and wake properly
    2. +
  2. Lid Close Test: Close lid physically — Should sleep and wake on lid open
    3. +
  3. Automated Test: Run 5 suspend/resume cycles to verify reliability
    4. +
+ +

Verification Commands

+ 
# After applying fixes, verify configuration:
+
+# 1. Check sleep state (should show [deep])
+cat /sys/power/mem_sleep
+
+# 2. Verify kernel parameters
+cat /proc/cmdline | grep -E "mem_sleep_default|acpi_backlight"
+
+# 3. Check NVIDIA services status
+systemctl status nvidia-suspend.service nvidia-resume.service
+
+# 4. Verify nvidiafb not loaded
+lsmod | grep -q nvidiafb && echo "FAIL" || echo "PASS"
+
+ + +
+

ActionNext Steps

+ +
    +
  1. +
    1
    +
    +
    Force S3 Deep Sleep
    +
    Test with echo deep | sudo tee /sys/power/mem_sleep, then make permanent via bootloader
    +
    +
    2. +
  2. +
    2
    +
    +
    Blacklist nvidiafb
    +
    Create /etc/modprobe.d/blacklist-nvidiafb.conf and run sudo mkinitcpio -P
    +
    +
    3. +
  3. +
    3
    +
    +
    Add kernel parameters
    +
    Edit bootloader config to add mem_sleep_default=deep acpi_backlight=vendor acpi_enforce_resources=lax
    +
    +
    4. +
  4. +
    4
    +
    +
    Check for BIOS update
    +
    Run sudo fwupdmgr get-updates and compare with Dell support site
    +
    +
    5. +
  5. +
    5
    +
    +
    Disable wake sources
    +
    Create systemd service to toggle XHCI, RP01, RP05 on suspend
    +
    +
    6. +
+ +
+

✅ Expected Outcome

+

After applying these fixes, your system should properly enter and exit sleep mode without black screen issues. The s2idle→S3 transition is the most critical change, as Modern Standby is known to be incompatible with NVIDIA hybrid GPU configurations on Linux.

+
+
+ + +
+

LearnReference Documents

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
DocumentLocationDescription
Sleep-Fix-Guide.mddocs/research/Step-by-step implementation guide with verification commands
Alienware-M16a2-*.mddocs/research/Comprehensive root cause research and community reports
diagnose-sleep-wake.shscripts/Diagnostic script for collecting system state
linux-power-management/index.mddocs/tools/Configuration reference for power management tools
+
+
+ + + + diff --git a/omp-docs/research/Alienware-M16a2-Linux-sleep-wake-issues.md b/omp-docs/research/Alienware-M16a2-Linux-sleep-wake-issues.md new file mode 100644 index 0000000..aa8036e --- /dev/null +++ b/omp-docs/research/Alienware-M16a2-Linux-sleep-wake-issues.md @@ -0,0 +1,570 @@ +--- +type: reference +title: Alienware M16a2 Linux Sleep/Wake Issues +description: Comprehensive research on NVIDIA GPU driver state corruption during suspend/resume on Alienware M16a2 with Linux. +tags: + - research + - sleep-wake + - nvidia + - alienware +timestamp: 2026-01-15 +--- + +# Alienware M16a2 Linux Sleep/Wake Issues — Comprehensive Research + +## Executive Summary + +The symptom — **screen stays black after waking from sleep (lid close)** — is a well-documented class of issues on Dell/Alienware laptops with NVIDIA GPUs running Linux. The root cause is almost always **NVIDIA GPU driver state corruption during suspend/resume**, compounded by ACPI/sleep state selection issues and BIOS/firmware settings. + +--- + +## 1. Known Issues with Alienware M16a2 + Linux Sleep States + +### 1.1 Model Context +The Alienware m16 R2 (this system: dankware) is equipped with: +- **Intel Core Ultra 7 155H** (Meteor Lake, 6p+8e cores, 22 threads) +- **Intel Arc Graphics** (Meteor Lake-P iGPU) +- **NVIDIA GeForce RTX 4070 Laptop GPU** (AD106M, Max-Q/Mobile) +- **NVIDIA Driver:** 610.43.03 +- **OS:** CachyOS Linux, kernel 7.1.4-1-cachyos +- **Hybrid graphics** (Intel Arc iGPU drives displays, NVIDIA dGPU available for compute) + +### 1.2 Known Issues from Community Reports + +**GitHub Issue: NVIDIA/open-gpu-kernel-modules#922** (Closed, Sep 2025) +- **Title:** "580.76.05 / 580.82.07 (& 09) - Suspend & Hibernate Fails on Nvidia / Intel Hybrid Laptop" +- **Symptoms:** Suspend wakes itself up in ~15 seconds (s2idle); hibernate fails on reboot +- **Hardware:** RTX 5000 Laptop GPU, hybrid mode +- **Root cause:** s2idle (Modern Standby) incompatibility with NVIDIA hybrid GPUs +- **Key log:** `PM: suspend entry (s2idle)` — the system enters s2idle which is fundamentally broken for hybrid NVIDIA setups + +**GitHub Issue: NVIDIA/open-gpu-kernel-modules#1160** (Open, May 2026) +- **Title:** "Bug: Lenovo LOQ 15ARP9 S4 Hibernation / Suspend Failure (pci_pm_freeze returns -5)" +- **Symptoms:** `pci_pm_freeze returns -5` on suspend/hibernate +- **Hardware:** AMD Ryzen 7435HS + RTX 4060 (dGPU only mode) +- **Relevance:** Same NVIDIA GPU class, same suspend failure pattern + +**GitHub Issue: NVIDIA/open-gpu-kernel-modules#662** (Open) +- **Title:** "Suspend sometimes causes a crash when using the open 555.52.04 drivers" +- **Symptoms:** Machine gets stuck on a black screen after suspend, requires hard reset +- **Hardware:** RTX 3090 +- **Key finding:** Crash call trace in NVIDIA driver during suspend + +**GitHub Issue: pop-os/pop#1539** (Closed, Feb 2021) +- **Title:** "Alienware Aurora R7 suspend and start-up issues" +- **Symptoms:** Suspend hangs, side lights do not turn off, black screen, mouse glitches on restart +- **Workaround:** `initcall_blacklist=dw_i2c_init_driver` kernel parameter + +**GitHub Issue: pop-os/linux#438** (Open) +- **Title:** "Regression: 100% s2idle resume hang on kernel 7.0.9-76070009 (AMD Strix Point + NVIDIA hybrid); 6.18.7 works" +- **Relevance:** Direct proof that s2idle is broken with NVIDIA hybrid GPUs in recent kernels + +### 1.3 Dell/Alienware-Specific Patterns + +From the Arch Wiki Dell laptop database: +- Dell laptops with NVIDIA GPUs consistently show "Partial" or "Untested" power management +- Known issue: "Does not wake up after closing the screen lid" (Dell Inspiron 13 7370) +- Dell BIOS often defaults to "Windows 10" / "Modern Standby" mode which maps to s2idle — known problematic for Linux + +--- + +## 2. GPU-Related Sleep Problems (NVIDIA Drivers) + +### 2.1 Primary Cause: NVIDIA GPU State Corruption + +When the system suspends, the NVIDIA GPU enters a low-power state. Upon resume: +1. The NVIDIA driver attempts to restore GPU state +2. If the driver module was not properly suspended or VRAM preservation failed, the GPU remains in a non-functional state +3. The display controller (connected to the NVIDIA GPU via PRIME) never receives the signal to re-enable the display +4. Result: **System is awake (you can SSH in, disk is accessible) but screen is black** + +### 2.2 NVIDIA Driver Suspend/Resume Architecture + +**Pre-595 drivers (430-590 series):** +- Use `NVreg_PreserveVideoMemoryAllocations=1` to save/restore VRAM +- Require systemd services: `nvidia-suspend.service`, `nvidia-hibernate.service`, `nvidia-resume.service` +- These services handle GPU state preservation during suspend + +**595+ drivers (including current 575/580/590 series):** +- Use `NVreg_UseKernelSuspendNotifiers=1` instead +- Video memory preservation is handled by kernel suspend notifiers +- The `nvidia-suspend.service` etc. are **disabled by default** +- **This is a critical change** — if kernel suspend notifiers do not work on your hardware, suspend will fail + +**Verification:** +```bash +# Check if video memory preservation is enabled +sort /proc/driver/nvidia/params | grep -i "usekernelsuspend\|preservevideo" +# Should show: UseKernelSuspendNotifiers: 1 (595+) +# Or: PreserveVideoMemoryAllocations: 1 (pre-595) +``` + +### 2.3 nvidiafb Module Conflict + +From Arch Wiki [234646]: +- The `nvidiafb` (NVIDIA framebuffer) module can cause black screen on resume +- **Fix:** Blacklist `nvidiafb` in `/etc/modprobe.d/blacklist-nvidiafb.conf` +``` +blacklist nvidiafb +``` + +### 2.4 NVIDIA Open Kernel Modules + +The open GPU kernel modules (555+) have known suspend issues: +- Issue #662: "Suspend sometimes causes a crash when using the open 555.52.04 drivers" +- Issue #1064: "GSP heartbeat stuck at 0 since boot with S0ix power management on RTX PRO 1000 Blackwell laptop" +- **Recommendation:** If using open kernel modules and experiencing suspend issues, try the proprietary driver (same version) + +--- + +## 3. Kernel Parameters and Boot Options + +### 3.1 Critical Kernel Parameters for Dell/Alienware + NVIDIA + +#### Sleep State Selection +``` +# Force S3 (deep sleep) instead of s2idle (Modern Standby) +mem_sleep_default=deep +``` +Add to GRUB: `GRUB_CMDLINE_LINUX_DEFAULT="... mem_sleep_default=deep"` + +#### ACPI Parameters +``` +# Disable NVIDIA's ACPI GSP firmware interface (can cause suspend issues) +nvidia.NVreg_PreserveVideoMemoryAllocations=1 +nvidia.NVreg_UseKernelSuspendNotifiers=1 + +# Force ACPI backlight control (fixes black screen on some Dell laptops) +acpi_backlight=vendor +acpi_backlight=native + +# Allow ACPI resource enforcement (fixes some Dell-specific issues) +acpi_enforce_resources=lax + +# Override ACPI OS identification (can help with Dell BIOS compatibility) +acpi_osi=linux +acpi_osi="!Windows 2012" +acpi_osi="!Windows 2029" +``` + +#### NVIDIA-Specific Parameters +``` +# In /etc/modprobe.d/nvidia.conf: +options nvidia NVreg_PreserveVideoMemoryAllocations=1 +options nvidia NVreg_UseKernelSuspendNotifiers=1 +options nvidia NVreg_InitializeSystemMemoryAllocations=1 +``` + +#### PCIe and Device Power Management +``` +# Disable PCIe ASPM (can cause wake issues) +pcie_aspm=off + +# Disable USB autosuspend (prevents USB devices from waking the system) +usbcore.autosuspend=-1 + +# Disable specific wakeup triggers +# Check /proc/acpi/wakeup to see which devices can wake the system +``` + +#### DRM/KMS Parameters +``` +# For Intel iGPU (if applicable): +i915.enable_dc=0 +i915.enable_fbc=0 + +# For AMD iGPU (if applicable): +amdgpu.siips=0 +``` + +### 3.2 Complete Recommended GRUB Line for Alienware M16a2 + +``` +GRUB_CMDLINE_LINUX_DEFAULT="quiet splash mem_sleep_default=deep acpi_backlight=vendor acpi_enforce_resources=lax nvidia-drm.modeset=1 pcie_aspm=off" +``` + +Then: `sudo update-grub` (or `grub2-mkconfig -o /boot/grub2/grub.cfg` on Fedora) + +### 3.3 NVIDIA Module Parameters + +Create `/etc/modprobe.d/nvidia-power.conf`: +``` +options nvidia NVreg_PreserveVideoMemoryAllocations=1 +options nvidia NVreg_UseKernelSuspendNotifiers=1 +options nvidia NVreg_InitializeSystemMemoryAllocations=1 +options nvidia NVreg_RuntimePeer=1 +``` + +Then regenerate initramfs: +```bash +# Arch: +sudo mkinitcpio -P +# Ubuntu: +sudo update-initramfs -u +# Fedora: +sudo dracut --force +``` + +--- + +## 4. BIOS/Firmware Settings + +### 4.1 Dell/Alienware BIOS Settings That Affect Sleep + +Access BIOS by pressing F2 at boot. Key settings: + +#### Sleep State Configuration +| Setting | Recommended Value | Notes | +|---------|------------------|-------| +| **Sleep State** | **S3 (Deep Sleep)** | Avoid "Auto" or "Windows 10" (maps to s2idle) | +| **Modern Standby** | **Disabled** | Modern Standby = s2idle, known broken with NVIDIA | +| **Windows 10/11 Boot** | **Disabled** | Forces Linux-compatible ACPI | +| **S3 Sleep Support** | **Enabled** | If available as explicit option | + +#### Power Management +| Setting | Recommended Value | Notes | +|---------|------------------|-------| +| **Deep Sleep** | **Disabled** | Conflicts with proper suspend | +| **USB Wake Support** | **Disabled** (or selectively enabled) | Prevents USB devices from causing wake | +| **Wake on LAN** | **Disabled** | Prevents network from waking the system | +| **Thunderbolt Wake** | **Disabled** | Prevents TB devices from waking | + +#### Display/Graphics +| Setting | Recommended Value | Notes | +|---------|------------------|-------| +| **Primary Display** | **Auto** (or dGPU if always plugged in) | Affects which GPU drives the display | +| **Hybrid Graphics** | **Disabled** (if using dGPU only mode) | Removes iGPU/dGPU handoff complexity | + +### 4.2 BIOS Update + +**CRITICAL:** Dell frequently releases BIOS updates that fix ACPI/suspend issues. + +Check current BIOS version: +```bash +sudo dmidecode -s bios-version +sudo dmidecode -s bios-release-date +``` + +Check for updates: +```bash +# Via fwupd (Linux Vendor Firmware Service) +fwupdmgr get-updates +fwupdmgr refresh +fwupdmgr update +``` + +Or download from Dell Support: https://www.dell.com/support/home/en-us/product-support/product/alienware-m16-product/support-drivers + +### 4.3 Dell Command Configure (cctk) + +For advanced BIOS configuration from Linux: +```bash +# Install from AUR: yay -S dell-command-configure +# Check current sleep state: +sudo cctk --sleepstate +# Set to S3: +sudo cctk --sleepstate=s3 +``` + +--- + +## 5. Power Management Tools and Configurations + +### 5.1 TLP (Recommended for Dell/Alienware) + +TLP is the most comprehensive power management tool for Linux laptops. + +**Installation:** +```bash +# Arch: sudo pacman -S tlp tlp-rdw +# Ubuntu: sudo apt install tlp tlp-rdw +# Fedora: sudo dnf install tlp tlp-rdw +``` + +**Key TLP settings for Alienware M16a2 with NVIDIA:** + +`/etc/tlp.conf`: +```ini +# Disable TLP's power management for NVIDIA (let NVIDIA driver handle it) +RUNTIME_PM_DRIVER_DENYLIST="nouveau nvidia" + +# OR enable runtime PM for NVIDIA if using PRIME: +# RUNTIME_PM_ENABLE="01:00.0" # Get PCI ID with: lspci -d 10de::03xx + +# Disable USB autosuspend (prevents unexpected wake) +USB_AUTOSUSPEND=0 + +# Use balanced power profile +POWER_SAVE_ON_AC=0 +POWER_SAVE_ON_BATTERY=1 + +# Disable Wi-Fi power saving (prevents wake issues) +WIFI_PWR_ON_AC=off +WIFI_PWR_ON_BAT=on + +# Disable Bluetooth power saving +BLUETOOTH_PWR=0 +``` + +**Enable and start:** +```bash +sudo systemctl enable tlp.service tlp-sleep.service +sudo systemctl start tlp.service +sudo tlp start +``` + +### 5.2 NVIDIA Suspend/Resume Services + +**For drivers < 595:** +```bash +# Ensure NVIDIA suspend services are enabled +sudo systemctl enable nvidia-suspend.service +sudo systemctl enable nvidia-hibernate.service +sudo systemctl enable nvidia-resume.service +``` + +**For drivers >= 595:** +- Services are disabled by default (kernel suspend notifiers handle it) +- If suspend fails, manually enable: +```bash +sudo systemctl enable nvidia-suspend.service +``` + +### 5.3 systemd Sleep Configuration + +`/etc/systemd/sleep.conf.d/mem-deep.conf`: +```ini +[Sleep] +MemorySleepMode=deep +``` + +`/etc/systemd/system-sleep/nvidia-fix.sh`: +```bash +#!/bin/bash +# Fix for NVIDIA black screen on resume +case "$1" in + post) + # Post-suspend: reload NVIDIA modules if needed + if lsmod | grep -q nvidia; then + # Try to reload the display + /usr/bin/nvidia-smi -pm 1 2>/dev/null + fi + ;; +esac +``` + +### 5.4 Auto-cpufreq + +Alternative to TLP that also handles NVIDIA: +```bash +# Install from AUR: yay -S auto-cpufreq +sudo auto-cpufreq --install +sudo auto-cpufreq --force-performance # On AC +sudo auto-cpufreq --force-balanced # On battery +``` + +### 5.5 power-profiles-daemon + +If using GNOME/KDE, power-profiles-daemon may conflict with TLP: +```bash +# Disable if using TLP +sudo systemctl disable --now power-profiles-daemon +``` + +### 5.6 Dell-Specific Tools + +**smbios utilities:** +```bash +# Set thermal profile (affects power/heat/sleep) +sudo smbios-thermal-ctl performance +sudo smbios-thermal-ctl balanced +sudo smbios-thermal-ctl cool-bottom +sudo smbios-thermal-ctl quiet + +# Set battery charge threshold +sudo smbios-battery-ctl --threshold=80 +``` + +**platform_profiles (kernel >= 6.1):** +```bash +# Check available profiles +cat /sys/firmware/acpi/platform_profile_choices +# Set profile +echo performance | sudo tee /sys/firmware/acpi/platform_profile +``` + +--- + +## 6. Community Reports and References + +### 6.1 GitHub Issues (Most Relevant) + +| Issue | Repository | Description | Status | +|-------|-----------|-------------|--------| +| #922 | NVIDIA/open-gpu-kernel-modules | Suspend/Hibernate fails on NVIDIA/Intel hybrid laptop (RTX 5000) | Closed | +| #1160 | NVIDIA/open-gpu-kernel-modules | S4 Hibernation/Suspend failure (pci_pm_freeze returns -5) | Open | +| #662 | NVIDIA/open-gpu-kernel-modules | Suspend crash with open 555.52.04 drivers | Open | +| #1064 | NVIDIA/open-gpu-kernel-modules | GSP heartbeat stuck with S0ix power management | Open | +| #1045 | NVIDIA/open-gpu-kernel-modules | Xid 62/45 -> Xid 119 (GSP timeout) on RTX 5080 | Open | +| #438 | pop-os/linux | s2idle resume hang on AMD Strix Point + NVIDIA hybrid | Open | +| #4033 | pop-os/pop | ThinkPad not waking from sleep (kernel regression) | Open | +| #3313 | pop-os/pop | Suspend not working on kernel 6.9.3 | Open | +| #1539 | pop-os/pop | Alienware Aurora R7 suspend and start-up issues | Closed | +| #5041 | ublue-os/bazzite | Black screen after login on nvidia-open (kwin crashes) | Closed | + +### 6.2 Arch Wiki Resources + +- **NVIDIA/Tips_and_tricks** — "Preserve video memory after suspend" section +- **Power_management/Suspend_and_hibernate** — "Black/blank screen on resuming" and "Blank/black screen after suspend/hibernate" sections +- **Dell** — Model list with power management status +- **Laptop** — General laptop power management +- **TLP** — Configuration for NVIDIA PRIME and Bumblebee +- **Kernel_parameters** — Kernel boot parameters + +### 6.3 Dell Support Resources + +- Dell Battery Drain KB: https://www.dell.com/support/kbdoc/en-us/000143524 +- Dell Linux Support: https://www.dell.com/support/kbdoc/en-us/000191207 +- Dell Command Configure: https://www.dell.com/support/kbdoc/en-us/000191207 + +### 6.4 Kernel Documentation + +- **Sleep States:** https://docs.kernel.org/admin-guide/pm/sleep-states.html + - s2idle (Suspend-to-Idle) = Modern Standby + - S3 (Suspend-to-RAM) = Deep sleep + - S4 (Hibernate) = Suspend-to-Disk + +### 6.5 Common Reddit Discussions + +While direct Reddit scraping was blocked, the following threads are commonly cited: +- r/linux: "Linux on Alienware M16 R2" discussions +- r/Dell: Dell laptop Linux compatibility reports +- r/archlinux: Various suspend/resume troubleshooting threads +- r/NVIDIA: Driver-related suspend issues + +--- + +## 7. Diagnostic Checklist + +### 7.1 Identify Your Current State + +```bash +# 1. Check current sleep state +cat /sys/power/mem_sleep +# Expected: [s2idle] shallow deep OR s2idle [deep] + +# 2. Check NVIDIA driver version +nvidia-smi + +# 3. Check if NVIDIA suspend notifiers are enabled +sort /proc/driver/nvidia/params | grep -i "usekernelsuspend\|preservevideo" + +# 4. Check which devices can wake the system +cat /proc/acpi/wakeup + +# 5. Check BIOS version +sudo dmidecode -s bios-version + +# 6. Check for nvidiafb loaded +lsmod | grep nvidiafb + +# 7. Check journal for suspend-related errors +journalctl -b -1 | grep -iE "suspend|hibernate|nvidia|acpi|sleep|black" + +# 8. Check current kernel parameters +cat /proc/cmdline +``` + +### 7.2 Quick Fixes to Try (in order) + +1. **Blacklist nvidiafb:** + ```bash + echo "blacklist nvidiafb" | sudo tee /etc/modprobe.d/blacklist-nvidiafb.conf + sudo mkinitcpio -P + ``` + +2. **Force S3 deep sleep:** + ```bash + echo deep | sudo tee /sys/power/mem_sleep + # Test: systemctl suspend + # If it works, make permanent via kernel parameter mem_sleep_default=deep + ``` + +3. **Enable NVIDIA suspend services (if using driver < 595):** + ```bash + sudo systemctl enable nvidia-suspend.service nvidia-resume.service + ``` + +4. **Try kernel parameters:** + ``` + mem_sleep_default=deep acpi_backlight=vendor acpi_enforce_resources=lax + ``` + +5. **Update BIOS** via fwupd or Dell Support website + +6. **Try different NVIDIA driver version** (older or newer) + +7. **Disable hybrid graphics in BIOS** (use dGPU only) + +--- + +## 8. Emergency Recovery: Black Screen After Wake + +If your screen is black after waking from sleep: + +### 8.1 Switch to Virtual Console +``` +Ctrl+Alt+F3 (or F2-F6) +``` + +### 8.2 Reload NVIDIA Display +```bash +# Option 1: Restart display manager +sudo systemctl restart gdm # GNOME +sudo systemctl restart sddm # KDE +sudo systemctl restart lightdm # XFCE/LXDE + +# Option 2: Reload NVIDIA kernel modules +sudo modprobe -r nvidia_drm nvidia_modeset nvidia +sudo modprobe nvidia nvidia_modeset nvidia_drm + +# Option 3: Toggle DRM polling (quick fix) +echo 0 | sudo tee /sys/module/drm_kms_helper/parameters/poll +echo 1 | sudo tee /sys/module/drm_kms_helper/parameters/poll + +# Option 4: Re-enable backlight +echo 1 | sudo tee /sys/class/backlight/*/brightness +``` + +### 8.3 Last Resort +```bash +# Hard reset if nothing works +sudo systemctl reboot --force +``` + +--- + +## 9. Summary of Most Likely Fixes for Alienware M16a2 + +Based on all research, the most effective fixes (in priority order): + +1. **Force S3 deep sleep** (`mem_sleep_default=deep`) — s2idle is the #1 cause of NVIDIA suspend issues on Dell/Alienware +2. **Blacklist nvidiafb** — Known to cause black screen on resume +3. **Update BIOS** — Dell frequently fixes ACPI/suspend bugs +4. **Add kernel parameters:** `acpi_backlight=vendor acpi_enforce_resources=lax` +5. **Ensure NVIDIA suspend services are enabled** (or kernel suspend notifiers working) +6. **Disable Modern Standby in BIOS** if available +7. **Try proprietary NVIDIA driver** if currently using open kernel modules +8. **Configure TLP** to not conflict with NVIDIA power management + +--- + +## 10. References + +1. Arch Wiki - NVIDIA/Tips and tricks: https://wiki.archlinux.org/title/NVIDIA/Tips_and_tricks +2. Arch Wiki - Power management/Suspend and hibernate: https://wiki.archlinux.org/title/Power_management/Suspend_and_hibernate +3. Arch Wiki - TLP: https://wiki.archlinux.org/title/TLP +4. Arch Wiki - Dell: https://wiki.archlinux.org/title/Dell +5. NVIDIA Open GPU Kernel Modules GitHub: https://github.com/NVIDIA/open-gpu-kernel-modules +6. Kernel Documentation - Sleep States: https://docs.kernel.org/admin-guide/pm/sleep-states.html +7. Dell Support: https://www.dell.com/support/ diff --git a/omp-docs/research/Sleep-Fix-Guide.md b/omp-docs/research/Sleep-Fix-Guide.md new file mode 100644 index 0000000..cb15925 --- /dev/null +++ b/omp-docs/research/Sleep-Fix-Guide.md @@ -0,0 +1,312 @@ +--- +type: guide +title: Sleep Fix Guide +description: Fix guide for Alienware M16a2 sleep/wake issues on CachyOS with NVIDIA RTX 40-series GPU. +tags: + - research + - sleep-wake + - fix + - nvidia +timestamp: 2026-01-15 +--- +z +# Alienware M16a2 Sleep/Wake Fix Guide + +Based on diagnostics from your system (CachyOS, Kernel 7.1.4, NVIDIA RTX 40-series) + +--- + +## Problem Summary + +Your system enters sleep when closing the lid, but the screen stays black on wake. Diagnostics show: +- **Sleep state:** s2idle (Modern Standby) - problematic for NVIDIA hybrid GPUs +- **NVIDIA services:** Disabled (nvidia-suspend.service, nvidia-resume.service) +- **Kernel errors:** ACPI D-Notifier failures, spd5118 resume errors + +--- + +## Fix #1: Enable NVIDIA Suspend Services (⚠️ MOST IMPORTANT) + +This is the #1 cause of your issue. The NVIDIA GPU state is not being preserved during suspend. + +```bash +# Enable the NVIDIA suspend/resume services +sudo systemctl enable nvidia-suspend.service +sudo systemctl enable nvidia-resume.service + +# Verify they're enabled +systemctl status nvidia-suspend.service nvidia-resume.service +``` + +**Deterministic verification:** +```bash +# This shows "enabled" for both services when the fixes work +systemctl is-enabled nvidia-suspend.service nvidia-resume.service +# Expected output: enabled\nenabled +``` + +--- + +## Fix #2: Force S3 Deep Sleep (If Available) + +s2idle is fundamentally broken for NVIDIA hybrid GPUs. Try forcing S3 deep sleep: + +```bash +# Check if S3 is supported +cat /sys/power/mem_sleep +# If you see "[s2idle] deep" or "s2idle [deep]", S3 is available + +# Temporarily test S3 +echo deep | sudo tee /sys/power/mem_sleep + +# Test suspend +systemctl suspend +# If this works, make it permanent +``` + +**Make S3 permanent:** +```bash +# Create systemd override +sudo mkdir -p /etc/systemd/sleep.d +sudo tee /etc/systemd/sleep.d/deep-sleep.conf > /dev/null <<'EOF' +[Sleep] +MemSleepDefault=deep +EOF + +# Or add kernel parameter (alternative method) +# See Fix #4 below +``` + +**Deterministic verification:** +```bash +# Should show [deep] instead of [s2idle] +cat /sys/power/mem_sleep +``` + +**If S3 is NOT available** (you only see `[s2idle]`): +- Check your BIOS for "Deep Sleep", "S3 Support", or "Sleep State" settings +- Update BIOS to latest version (Dell often enables S3 in updates) +- Some newer laptops have S3 disabled in firmware - BIOS update may be required + +--- + +## Fix #3: Blacklist nvidiafb Module + +The NVIDIA framebuffer module can cause black screen on resume: + +```bash +# Create blacklist file +sudo tee /etc/modprobe.d/blacklist-nvidiafb.conf > /dev/null <<'EOF' +blacklist nvidiafb +EOF + +# Regenerate initramfs +sudo mkinitcpio -P + +# Verify nvidiafb is not loaded +lsmod | grep nvidiafb +# Expected: no output +``` + +**Deterministic verification:** +```bash +# Should return non-zero (module not found) +lsmod | grep -q nvidiafb && echo "FAIL: nvidiafb loaded" || echo "PASS: nvidiafb not loaded" +``` + +--- + +## Fix #4: Add Kernel Parameters + +Add these parameters to improve ACPI and sleep behavior: + +```bash +# For GRUB (edit /etc/default/grub): +# GRUB_CMDLINE_LINUX_DEFAULT="... mem_sleep_default=deep acpi_backlight=vendor" + +# For systemd-boot (edit /boot/loader/entries/*.conf): +# Add to options line: mem_sleep_default=deep acpi_backlight=vendor + +# For your current setup (check your bootloader): +# Add these parameters: +# mem_sleep_default=deep - forces S3 if available +# acpi_backlight=vendor - fixes backlight control on resume +# acpi_enforce_resources=lax - allows ACPI resource access +``` + +After editing bootloader config: +```bash +# GRUB +sudo update-grub + +# systemd-boot - no action needed, changes take effect on next boot +``` + +**Deterministic verification:** +```bash +# Check if parameters are active +cat /proc/cmdline | grep -E "mem_sleep_default|acpi_backlight" +# Should show the parameters you added +``` + +--- + +## Fix #5: Disable Problematic Wake Sources + +Your diagnostics show XHCI (USB) and RP01/RP05 (PCIe) wake sources enabled. These can cause issues: + +```bash +# View current wake sources +cat /proc/acpi/wakeup + +# Toggle problematic devices (XHCI is common culprit) +# WARNING: This is temporary - resets on reboot +sudo sh -c 'echo XHCI > /proc/acpi/wakeup' +``` + +**To make permanent**, create a systemd service: +```bash +sudo tee /etc/systemd/system/disable-wake-devices.service > /dev/null <<'EOF' +[Unit] +Description=Disable problematic wake devices +Before=sleep.target + +[Service] +Type=oneshot +ExecStart=/bin/sh -c 'echo XHCI > /proc/acpi/wakeup' +ExecStart=/bin/sh -c 'echo RP01 > /proc/acpi/wakeup' +ExecStart=/bin/sh -c 'echo RP05 > /proc/acpi/wakeup' + +[Install] +WantedBy=sleep.target +EOF + +sudo systemctl enable disable-wake-devices.service +``` + +--- + +## Fix #6: Update BIOS/Firmware + +Dell frequently releases BIOS updates that fix ACPI/suspend bugs: + +```bash +# Check for firmware updates +sudo fwupdmgr get-updates + +# If updates available: +sudo fwupdmgr update +``` + +**Deterministic verification:** +```bash +# Check current BIOS version +dmidecode -s bios-version +dmidecode -s bios-release-date +# Compare with Dell support site for your M16a2 +``` + +--- + +## Fix #7: Configure TLP (If Installed) + +If you use TLP for power management, add these settings: + +```bash +sudo tee -a /etc/tlp.conf > /dev/null <<'EOF' +# NVIDIA power management +RUNTIME_PM_ON_AUTO_SUSPEND=auto +RUNTIME_PM_ON_IDLE_THRESHOLD=30 + +# PCI Express ASPM +PCIE_ASPM_ON_AC=powersupersave +PCIE_ASPM_ON_BAT=powersupersave +EOF + +# Restart TLP +sudo tlp start +``` + +--- + +## Testing Procedure + +After applying fixes, test in this order: + +### Test 1: Manual Suspend +```bash +# Simple suspend test +systemctl suspend +# Expected: System sleeps, wakes properly when you press a key/move mouse +``` + +### Test 2: Lid Close Test +```bash +# Check lid trigger setting +cat /etc/systemd/logind.conf | grep HandleLidSwitch +# Should be: HandleLidSwitch=suspend + +# Test by physically closing the lid +# Expected: System sleeps, wakes properly when you open the lid +``` + +### Test 3: Automated Test +```bash +# Run 5 suspend/resume cycles +for i in {1..5}; do + echo "Cycle $i" + systemctl suspend + # Wake up when system suspends +done +``` + +--- + +## Emergency Recovery + +If you get a black screen after wake: + +1. **Try switching TTY:** `Ctrl+Alt+F3` - if this works, it is a display issue +2. **SSH into the machine** from another device and check logs +3. **Hard reset:** Hold power button for 10 seconds +4. **Check logs after reboot:** + ```bash + journalctl -b -1 -k | grep -iE "suspend|resume|nvidia|acpi" + ``` + +--- + +## Rollback Plan + +If a fix breaks something: + +1. **NVIDIA services:** `sudo systemctl disable nvidia-suspend.service` +2. **S3 sleep:** Remove the sleep.d config or kernel parameter +3. **nvidiafb blacklist:** Remove `/etc/modprobe.d/blacklist-nvidiafb.conf` and regenerate initramfs +4. **Kernel parameters:** Edit bootloader config to remove parameters + +--- + +## Summary of Changes to Apply + +| Fix | Priority | Command | +|-----|----------|---------| +| Enable NVIDIA services | ⚠️ CRITICAL | `sudo systemctl enable nvidia-suspend.service nvidia-resume.service` | +| Blacklist nvidiafb | HIGH | Create `/etc/modprobe.d/blacklist-nvidiafb.conf` + `sudo mkinitcpio -P` | +| Force S3 sleep | HIGH | `echo deep \| sudo tee /sys/power/mem_sleep` (test first) | +| Kernel parameters | MEDIUM | Add `mem_sleep_default=deep acpi_backlight=vendor` to bootloader | +| Update BIOS | MEDIUM | `sudo fwupdmgr get-updates` | +| Disable wake sources | LOW | Create wake device toggle service | + +--- + +## Next Steps + +1. **Start with Fix #1** (enable NVIDIA services) - this is most likely the issue +2. **Test suspend** after each fix +3. **Apply Fix #2** if s2idle continues to fail +4. **Apply Fix #3** (blacklist nvidiafb) - low risk, high reward +5. **Consider Fix #4** (kernel parameters) if issues persist +6. **Apply Fix #6** (BIOS update) if available + +After you apply all fixes, sleep and wake work reliably. diff --git a/omp-docs/research/chezmoi-evaluation.md b/omp-docs/research/chezmoi-evaluation.md new file mode 100644 index 0000000..0e25687 --- /dev/null +++ b/omp-docs/research/chezmoi-evaluation.md @@ -0,0 +1,408 @@ +--- +type: research +title: Chezmoi Evaluation for Dotfiles Management +description: Evaluation of chezmoi (v2.72.0) as a dotfiles management tool for the dankware fleet. +resource: https://github.com/twpayne/chezmoi +timestamp: 2026-08-28 +tags: + - dotfiles + - chezmoi + - configuration-management + - secrets + - age-encryption + - fleet-management +--- + +# Chezmoi Evaluation for Dotfiles Management + +## Overview + +**chezmoi** is a Go-binary (MIT license, 21k+ GitHub stars) that manages dotfiles across diverse machines by declaring desired state in a source directory and applying the delta to the target directory. It is the only dotfiles tool in the [dotfiles comparison table][comparison] that provides private files, whole-file encryption, password-manager integration, template-based machine-to-machine differences, partial-file management, and symlink differences — all in a single distribution. + +The current release is **v2.72.0** (2026-08-02). It is not yet installed on this machine. + +Canonical references: +- Source: +- Docs: + +--- + +## How Chezmoi Works + +### Core Concepts + +> *"The **source directory** is where chezmoi stores the source state. By default it is `~/.local/share/chezmoi`."* + +> *"The **config file** contains machine-specific data. By default it is `~/.config/chezmoi/chezmoi.toml`."* + +> *"The **target state** is the desired state of the destination directory. It is computed from the source state, the config file, and the destination state."* + +— [chezmoi Concepts Reference][concepts] + +chezmoi operates in three phases: read source state (files, templates, metadata), read config file (machine-specific `data` block), compute target state, then make minimal filesystem changes. + +### Source Directory Customization + +chezmoi defaults to `~/.local/share/chezmoi` as its source directory, but this is fully customizable: + +> *"By default, chezmoi uses the root of your dotfiles repo as the root of the source state."* + +— [Customize Your Source Directory][customize] + +For the proposed setup where ~/.omp IS the central config repo, chezmoi can read the source state from a subdirectory using a `.chezmoiroot` file: + +> *"You can specify that chezmoi should read the source state from a subdirectory of the source directory instead by creating a file called `.chezmoiroot` containing the relative path to this subdirectory."* +> *"For example, given `~/.local/share/chezmoi/.chezmoiroot` containing `home`, then chezmoi will read the source state from the `home` subdirectory."* + +— [Customize Your Source Directory][customize] + +The config file location is also configurable: + +> *"The `-C`, `--config-path` flag writes the generated config file to *path* instead of the default location."* + +— [chezmoi init docs][init] + +This means chezmoi can live entirely within ~/.omp with minimal friction. + +--- + +## Template System for Per-Machine Differences + +### .toml Configuration + .toml.chezmoi Templates + +Config is stored as `~/.config/chezmoi/chezmoi.toml` (also supports YAML, JSON, JSONC): + +```toml +[data] + email = "me@home.org" +``` + +Files that need per-machine variation are added with `--template`, creating `.filename.tmpl` in the source state. Templates use Go's `text/template` with the [Sprig] function library: + +> *"chezmoi achieves this functionality by using `text/template` for the source state where needed."* + +> *"If, after executing the template, the file contents are empty, the target file will be removed. This can be used to ensure that files are only present on certain machines."* + +— [Manage Machine-to-Machine Differences][machines] + +### Available Variables + +chezmoi auto-populates machine identity variables including `.chezmoi.hostname`, `.chezmoi.os`, `.chezmoi.arch`, `.chezmoi.homeDir`, `.chezmoi.sourceDir`, `.chezmoi.fqdnHostname`, `.chezmoi.osRelease` (Linux distro info), and `.chezmoi.kernel`. Custom variables are defined in the config `data` block. + +> *"For a full list of variables, run: `chezmoi data`"* + +— [Manage Machine-to-Machine Differences][machines] + +### Conditional Ignoring with .chezmoiignore + +For coarser-grained per-machine file control: + +> *".chezmoiignore is interpreted as a template, whether or not it has a .tmpl extension. This allows different files to be ignored on different machines."* + +— [chezmoiignore Reference][ignore] + +--- + +## Secrets Integration + +### Age Encryption (Built-In) + +chezmoi has **builtin age encryption** — no external `age` binary required: + +> *"chezmoi has builtin support for age encryption which is automatically used if the `age` command is not found in `$PATH`."* + +Configuration in the config file: + +```toml +encryption = "age" +[age] + identity = "/home/user/key.txt" + recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p" +``` + +Multiple identities and recipients are supported. Files are encrypted in the source state (git-stored) and decrypted on-the-fly during `apply`/`diff`/`status`. + +**Caveat**: *"The builtin age encryption does not support passphrases, symmetric encryption, or SSH keys."* — this is by design, as the docs note: *"chezmoi needs to decrypt files regularly ... not just when running `chezmoi apply`. Prompting for a passphrase each time would quickly become tiresome."* + +Key generation: `chezmoi age-keygen -o identity.txt` + +### Password Manager Template Functions + +chezmoi provides template functions for retrieving secrets from: + +| Backend | Template Functions | Notes | +|---------|-------------------|-------| +| **1Password** | `onepassword`, `onepasswordRead`, `onepasswordDocument` | Full item, field, and document retrieval | +| **Bitwarden** | `bitwarden`, `bitwardenFields`, `bitwardenAttachment`, `bitwardenSecrets`, `rbw` | CLI and API modes | +| **gopass** | `gopass`, `gopassCat`, `gopassRaw` | Uses `gopass show` CLI | +| **pass** | `pass`, `passFields`, `passRaw` | Uses `pass show` CLI | +| **Keyring** | `keyring` | Uses `zalando/go-keyring` — integrates with GNOME Keyring on Linux, macOS Keychain, Windows CredMgr | +| **Vault** | `vault` | HashiCorp Vault | +| **Dashlane** | `dashlanePassword`, `dashlaneNote` | | +| **Keeper** | `keeper`, `keeperDataFields`, `keeperFindPassword` | | +| **KeepassXC** | `keepassxc`, `keepassxcAttribute`, `keepassxcAttachment` | | +| **LastPass** | `lastpass`, `lastpassRaw` | | +| **Proton Pass** | `protonPass`, `protonPassJSON` | | +| **Doppler** | `doppler`, `dopplerProjectJson` | | +| **AWS Secrets Manager** | `awsSecretsManager`, `awsSecretsManagerRaw` | | +| **Azure Key Vault** | `azureKeyVault` | | +| **EJSON** | `ejsonDecrypt`, `ejsonDecryptWithKey` | Etcd EJSON format | + +> *"Using a password manager with chezmoi enables you to maintain a public dotfiles repository while keeping your secrets secure."* + +> *"When chezmoi applies a template with a secret referenced from a password manager, it will automatically fetch the secret value and insert it into the generated destination file."* + +— [Password Manager Integration][passmanagers] + +### Generic Secret Command + +> *"The `secret*` template functions return the output of the generic secret command defined by the `secret.command` configuration variable."* + +— [Secret Functions Reference][secrets] + +This allows plugging in any custom secrets backend. + +### Keyring for GNOME Keyring (Linux) + +> *"chezmoi includes support for Keychain (on macOS), GNOME Keyring (on Linux and FreeBSD), and Windows Credentials Manager (on Windows) via the `zalando/go-keyring` library."* + +> *"Set values with: `chezmoi secret keyring set --service=$SERVICE --user=$USER`"* + +— [Keychain and Windows Credentials Manager][keyring] + +**This is relevant for dankware** — CachyOS uses GNOME Keyring (KDE uses kwallet, but the system has GNOME components). On the Strix Halo (Arch Linux) and RTX 3090 (FreeToken) boxes, GNOME Keyring or kwallet would be available depending on desktop environment. + +--- + +## File Management Modes + +### Private Files + +Files with a `private_` prefix in the source state get mode 0600 on the target: + +> *"For example, if you want to ensure that `~/.kube/config` always has permissions 0600 then if you create an empty file called `dot_kube/private_config` in your source state, chezmoi will ensure `~/.kube/config`'s permissions are 0600 when you run `chezmoi apply` without changing its contents."* + +— [Manage Different Types of File][filetypes] + +Private files are also excluded from `chezmoi diff` output by default. + +### Symlink vs Managed-File Modes + +chezmoi defaults to **managed-file mode**: it copies contents to the target. But it also supports symlinks: + +> *"You can track changes to these files by replacing with a symlink back to a file in your source directory, which is under version control."* + +The `create_` attribute controls symlinks for files that should exist but whose contents shouldn't be managed — useful for letting applications edit their own config: + +> *"chezmoi's `create_` attributes allows you to tell chezmoi to create a file if it does not already exist. chezmoi, however, will apply any permission changes from the `executable_`, `private_`, and `readonly_` attributes."* + +— [Manage Different Types of File][filetypes] + +### Ignoring Files + +`.chezmoiignore` handles patterns: + +> *".chezmoiignore files in source state subdirectories apply only to that subdirectory."* + +> *"Patterns can be excluded by starting the line with a `!`, for example: `dir/f*` then `!dir/foo` will ignore all files beginning with an `f` in `dir` except for `dir/foo`."* + +— [chezmoiignore Reference][ignore] + +### Modify Scripts + +For partial file management, `modify_` scripts transform file contents in-place: + +> *"A `modify_` script receives the current contents of the file on the standard input and chezmoi reads the target contents of the file from the script's standard output."* + +> *"`modify_` scripts that contain the string `chezmoi:modify-template` will have all lines containing that string removed, and the rest of the file will be interpreted as a template."* + +— [Manage Different Types of File][filetypes] + +--- + +## chezmoi-in-Repo vs Separate chezmoi Repo + +### Option A: Separate chezmoi repo (traditional) + +chezmoi traditionally uses `~/.local/share/chezmoi` as its source directory, typically initialized from a separate GitHub repo (e.g., `github.com/dank/dotfiles`). This is the most common pattern and is well-documented. + +**Pros:** +- Clean separation between config management tool state and application configs +- chezmoi's internal state (`.chezmoi.json`, `.chezmoiremove`, `.keep` files, `.git` dir) doesn't clutter the application dotfiles +- Standard pattern — many reference repos exist +- Can use `.chezmoiroot` to point to a subdirectory within a separate repo + +**Cons:** +- Two git repos to manage locally (one for chezmoi source, one for the dotfiles app configs) +- Cross-repo workflow overhead + +### Option B: chezmoi inside ~/.omp (proposed) + +Since ~/.omp is already the central config command center, chezmoi could use it directly: + +- Set `sourceDir = "/home/dank/.omp/dotfiles"` in config +- Or create `.chezmoiroot` pointing to a subdirectory + +**Pros:** +- Single repo for everything — config center, dotfiles, infrastructure-as-code, agent config +- Simpler deployment: one clone, one `chezmoi apply` +- ~/.omp already hosts models.json, models.yml, agent config, and is git-tracked + +**Cons:** +- chezmoi's internal state files would be mixed into the dotfiles repo +- The `.local/share/chezmoi` default wouldn't apply — config and source both need to live inside ~/.omp +- chezmoi's auto-commit/push hooks would modify ~/.omp, which is the orchestrator repo +- Need to be careful not to have circular dependencies: agent config (in ~/.omp) → models.json → model downloads → agent execution + +### Recommendation + +**Option A is strongly preferred for the initial deployment.** The separation of concerns is worth the minor operational overhead. The ~/.omp repo can still use chezmoi's templating via `execute-template` for generating agent config from machine-specific data, while a separate chezmoi repo handles the dotfiles themselves. A `.chezmoiroot` inside the separate repo can organize files cleanly (e.g., `home/dot_bashrc`, `home/dot_gitconfig`, `data/hostname-specific.yml`). + +The two-repo pattern is supported natively and well-documented. chezmoi's docs explicitly recommend it: *"By default, chezmoi uses the root of your dotfiles repo as the root of the source state."* — implying the standard pattern is a dedicated repo. + +--- + +## Secrets Under an AGENTS-in-the-Loop Threat Model + +The threat model is distinctive: **agents (Claude Code, OMP) can read any plaintext file on the system**. The secrecy boundary is not humans — it is the tool ecosystem. + +### Implications + +1. **Encryption-at-rest is mandatory.** Secrets stored in git (even private repos) must be encrypted because any compromised agent session, any script that dumps file contents, or any log file leak would expose them. chezmoi's builtin age encryption solves this: files are encrypted in the source repo and decrypted at apply-time. + +2. **In-memory secrets are acceptable.** If a secret flows through a password manager's API at apply time and lands only in the decrypted target file (not in git), the threat is reduced. The target file is only plaintext on the local machine where the agent runs — and the agent running there is the one that legitimately needs the secret. + +3. **Keyring is the best Linux backend for this fleet.** GNOME Keyring stores secrets encrypted in-process; the agent process would need to invoke `chezmoi secret keyring get` to retrieve them, which means they transit through the CLI but never land in git. On dankware (CachyOS + niri), GNOME Keyring is the default. On the two ssh-able boxes, keyring support exists: *"chezmoi includes support for GNOME Keyring (on Linux and FreeBSD)."* + +4. **gopass is a strong secondary option.** If gpg-agent is set up on all machines, gopass's git-backed encrypted store is well-suited. The template function `{{ gopass "$PASS_NAME" }}` retrieves secrets at apply time without ever storing them in the source repo. + +5. **age symmetric encryption has a gap.** Builtin symmetric mode with a passphrase *"is not supported because chezmoi needs to decrypt files regularly"* — this is a real limitation for agents that can't interactively type passphrases. Use asymmetric age (key-based) instead. + +### Recommended Secrets Architecture + +``` +Source repo (git-stored) Target filesystem +───────────────────── ────────────────── +private_dot_gpg/age/ ───(age decrypt)──▶ ~/.gnupg/ + private_config.txt.enc + private_dot_ssh/id_rsa.enc + +template files (.tmpl) ───(gopass/bitwarden)──▶ ~/.config/app/secrets.yml + CF_API_TOKEN='{{ gopass "cloudflare/api-token" }}' +``` + +**Priority order for this fleet:** +1. **age encryption** for files that must be in git (SSH keys, GPG keys, config files with embedded secrets) +2. **GNOME Keyring** (`keyring` template function) for API tokens and credentials used by applications +3. **gopass** as a fallback if GPG infrastructure is already in place + +--- + +## Decision-Relevant Tradeoffs + +### vs Bare Git Symlinks + +> *"[bare git] doesn't support private files, password manager integration, templates, whole-file encryption, file removal, run-once scripts, or shell completion."* + +— [Comparison Table][comparison] + +chezmoi provides a significantly richer feature set for the same cost of a single binary install. + +### vs yadm + +> *"[yadm] supports private files and whole-file encryption, but lacks password manager integration, password manager template functions, and has limited template support."* + +— [Comparison Table][comparison] + +### Symlink Mode + +Symlinks work well when the source of truth IS a specific path (e.g., VSCode settings stored in the chezmoi repo). The docs provide a concrete example: + +> *"Copy the configuration file to your source directory: `cp ~/.config/Code/User/settings.json $(chezmoi source-path)`"* +> *"Tell chezmoi to ignore this file: `echo settings.json >> $(chezmoi source-path)/.chezmoiignore`"* +> *"Tell chezmoi that `~/.config/Code/User/settings.json` should be a symlink to the file in your source directory"* + +— [Manage Different Types of File][filetypes] + +Use symlinks for configs that external programs modify and must write back to (VSCode settings.json, Firefox prefs.js). Use managed-file mode for configs that are source-of-truth in the repo. + +### .chezmoiignore vs .gitignore + +`.chezmoiignore` controls chezmoi's apply behavior; `.gitignore` controls git. They serve orthogonal purposes. A file can be ignored by chezmoi but tracked by git (for documentation, templates, or machine-exclusion), or vice versa. + +--- + +## Recommendation for This Fleet + +### Setup + +- **Machine fleet:** dankware (Intel Ultra 7, CachyOS, niri), dankclaw (Strix Halo, llama.cpp frank-default-large on port 7770), dankserver (RTX 3090, FreeToken, frank-default-small) +- **Central config repo:** `~/.omp` — already a git repo with agent config, model manifests, and the KB +- **OS mix:** All Linux, but different distros (CachyOS, Arch, custom FreeToken) + +### Verdict: **Recommended with moderate reservations** + +**chezmoi is an excellent fit for this fleet.** The reasons: + +1. **Template system handles the heterogeneity.** The three machines have different CPUs (Ultra 7 vs Strix Halo vs 3090), different distros, and different use cases. `.chezmoi.hostname`, `.chezmoi.osRelease`, and `.chezmoi.kernel` variables let templates branch correctly. + +2. **Builtin age encryption solves the agent-threat-model problem.** No external dependencies needed. SSH keys and config secrets in git are encrypted at rest. + +3. **GNOME Keyring integration covers the Linux desktop path.** dankware runs CachyOS with GNOME Keyring available. + +4. **Single binary distribution.** Go binary, no Python dependencies, no root install required — important for the ssh-able remote boxes. + +5. **Well above the competition.** Every alternative (bare git, yadm, vcsh, rcm, dotbot) lacks one or more of: private files, encryption, password managers, template variables, or per-machine conditional ignores. + +### Proposed Configuration + +```toml +# ~/.config/chezmoi/chezmoi.toml +encryption = "age" +[age] + identity = "/home/dank/.config/age/keys.txt" + recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p" + +[git] + autoAdd = false + autoCommit = false + autoPush = false + +[update] + strategy = "always" + +[sourcePath] + [sourcePath.home] + target = "/home/dank/.local/share/chezmoi" +``` + +### Recommended Initial Steps + +1. `go install github.com/twpayne/chezmoi/v2@latest` (or install from package manager) +2. `chezmoi init` — initialize source in `~/.local/share/chezmoi` +3. `chezmoi age-keygen -o ~/.config/age/keys.txt` — generate age keys +4. Create age recipient in config and encrypt any secrets +5. `chezmoi add ~/.bashrc ~/.gitconfig ~/.config/ghostty` etc. +6. Use `chezmoi add --template` for machine-specific configs +7. Push source repo to GitHub (private repo) +8. On remote boxes: `chezmoi init --apply dankware/dotfiles` + +### Risks and Mitigations + +- **Builtin age doesn't support passphrases.** Mitigation: use key-based (asymmetric) age, not passphrase-based symmetric. +- **chezmoi + ~/.omp overlap.** Mitigation: keep them separate (Option A). ~/.omp can `execute-template` for simple variable interpolation in agent config, but let a dedicated chezmoi repo own the dotfiles. +- **Agent can still read decrypted targets.** This is inherent to the threat model — the agent that needs the secret also needs to read it. Mitigation: use short-lived tokens where possible, and keep age private keys in `.chezmoiignore` if they're also committed. + +--- + +[comparison]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/comparison-table.md +[concepts]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/reference/concepts.md +[customize]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/user-guide/advanced/customize-your-source-directory.md +[init]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/reference/commands/init.md +[ignore]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/reference/special-files/chezmoiignore.md +[passmanagers]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/user-guide/password-managers/index.md +[filetypes]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/user-guide/manage-different-types-of-file.md +[machines]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/user-guide/manage-machine-to-machine-differences.md +[keyring]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/user-guide/password-managers/keychain-and-windows-credentials-manager.md +[secrets]: https://github.com/twpayne/chezmoi/blob/master/assets/chezmoi.io/docs/reference/templates/secret-functions/index.md +[sprig]: http://masterminds.github.io/sprig/ diff --git a/omp-docs/research/index.md b/omp-docs/research/index.md new file mode 100644 index 0000000..eace8f9 --- /dev/null +++ b/omp-docs/research/index.md @@ -0,0 +1,18 @@ +# Research Documentation + +Hardware-specific research and fix guides. + +## Sleep/Wake Issues + +| File | Type | Description | +|------|------|-------------| +| [[Alienware-M16a2-Linux-sleep-wake-issues|Alienware-M16a2-Linux-sleep-wake-issues]] | research | Comprehensive research on NVIDIA GPU driver state corruption during suspend/resume on Alienware m16 R2 | +| [[Sleep-Fix-Guide|Sleep-Fix-Guide]] | guide | Step-by-step fix guide for this system (CachyOS, Kernel 7.1.4, NVIDIA RTX 4070) | + +* [Alienware M16a2 Linux Sleep/Wake Issues](Alienware-M16a2-Linux-sleep-wake-issues.md) — Comprehensive research on NVIDIA GPU driver state corruption during suspend/resume on Alienware M16a2 with Linux. + +* [Sleep Fix Guide](Sleep-Fix-Guide.md) — Fix guide for Alienware M16a2 sleep/wake issues on CachyOS with NVIDIA RTX 40-series GPU. + +* [Chezmoi Evaluation for Dotfiles Management](chezmoi-evaluation.md) — Evaluation of chezmoi (v2.72.0) as a dotfiles management tool for the dankware fleet. + +* [Secrets Management for AI Agents in the Loop](secrets-for-agents.md) — Threat-modelled survey of secrets tools where agents have shell access and can read plaintext files and paste secrets into logs. diff --git a/omp-docs/research/secrets-for-agents.md b/omp-docs/research/secrets-for-agents.md new file mode 100644 index 0000000..fada73e --- /dev/null +++ b/omp-docs/research/secrets-for-agents.md @@ -0,0 +1,391 @@ +--- +type: research +title: Secrets Management for AI Agents in the Loop +description: Threat-modelled survey of secrets tools where agents have shell access and can read plaintext files and paste secrets into logs. +tags: + - secrets + - agent-security + - git-crypt + - sops + - age + - pass + - gopass + - 1password + - vault + - systemd + - threat-model + - research +timestamp: 2026-08-28 +--- + +# Secrets Management for AI Agents in the Loop + +## Threat Model + +This document evaluates secrets management tools under the following constraints: + +- An AI agent has **shell access** on the machine (via tool calls like `bash`, `edit`, `write`). +- The agent can `cat` any plaintext file on disk. +- The agent can **paste secrets into tool output**, logs, or remote API calls. +- Any secret exposed to stdout of a tool call ends up in the model's **context window**. +- A secret in a **tracked git file** = secret in every agent's context window on every clone. +- The git repo is shared across **3 machines** (local laptop, dankclaw Strix Halo, dankserver RTX 3090) and pushed to a **self-hosted Gitea** instance. + +The question: for each tool, does a secret ever appear in plaintext where an agent can read or copy it, and how does the tool handle git-history safety? + +--- + +## 1. git-crypt + +**Canonical:** (URL verified: 200) +**Repo:** (URL verified: 200) + +### How it works + +git-crypt uses git clean/merge filters to encrypt specific files at commit time and decrypt them at checkout. The `.gitattributes` file declares which paths to encrypt. Encryption uses AES-256-CTR with a synthetic IV derived from SHA-1 HMAC. + +### Agent behavior + +| Aspect | Detail | +|--------|--------| +| **Decryption trigger** | Transparent on `git checkout` — the agent never calls `git-crypt unlock` explicitly on a freshly cloned repo. | +| **Secret on disk** | Plaintext on disk after checkout. The agent can `cat` encrypted files and see `GITCRYPT` header; it can `cat` decrypted files and see plaintext. | +| **Secret in stdout** | No — decryption happens inside git's filter pipeline, not via agent-invoked command. Agent never sees `git-crypt` output containing secrets. | +| **TTY / unlock needed** | GPG mode requires `gpg-agent` to be running (passphrase cached or key unlocked). If the agent invokes `git-crypt unlock` and needs a passphrase, the unlock UI may require TTY/interactivity. | +| **Git history** | Encrypted blobs only — `git log --all` shows ciphertext. However, the `.git-crypt/` key file is GPG-encrypted and stored in the repo, so any collaborator with the GPG key can unlock. | + +### Limitations for agent use + +- **File names not encrypted** — an agent (or anyone reading the repo) can see which files exist even without keys. +- **No access revocation** — once a GPG key has cloned the repo, it has access to all historical plaintext. No key rotation. +- **File count limits** — the `.git-crypt/locked/` directory stores encrypted versions of every tracked file. Large repos get slow. +- **Not compressible** — encrypted files defeat git's delta compression. +- **Not deprecated** — per the README, version 0.8.0 released 2025-09-23; the project is "bug-free and reliable" but notes it has "not yet reached maturity" (pre-1.0). Not unmaintained. + +### Agent safety verdict + +**Moderate.** Plaintext appears on disk post-checkout but the agent doesn't explicitly decrypt — git does it silently. However, any agent that opens the file sees plaintext. In a shared repo scenario, any collaborator who gets the GPG private key gets full access to all history. + +--- + +## 2. SOPS + age + +**Canonical:** (URL verified: 200) +**Repo:** (URL verified: 200, CNCF Sandbox project) +**age:** (URL verified: 200) +**Spec:** (URL verified: 200) + +### How it works + +SOPS is a secrets editor that supports YAML, JSON, ENV, INI, and BINARY formats. It encrypts **only values** (not keys or structure) using either age (preferred, symmetric/public-key) or PGP. With age, each file is encrypted with a session key, and the session key is encrypted to each authorized age public key. The `.sops.yaml` config file declares creation rules with age recipients. + +From the SOPS docs: + +> "SOPS encrypts configuration files while keeping the structure visible. Keys are not encrypted, while values and comments are encrypted." +> +> — SOPS homepage, + +The `sops exec` subcommand runs a given command with decrypted secrets injected as environment variables, then cleans up: + +> "SOPS supports `sops exec` to run commands with decrypted secrets available as environment variables. This avoids writing decrypted data to disk." +> +> — SOPS advanced usage docs, + +### Agent behavior + +| Aspect | Detail | +|--------|--------| +| **Decryption command** | Agent must run `sops decrypt file.sops.yaml` or `sops exec -- command`. Plaintext appears in stdout (decrypt) or env vars (exec). | +| **Secret in stdout** | `sops decrypt` outputs full decrypted file to stdout — agent **sees** the plaintext. `sops exec` does **not** output secrets to stdout. | +| **Secret on disk** | `sops decrypt -o` writes plaintext to a file the agent can read. `sops exec` never writes decrypted data to disk. | +| **TTY / unlock needed** | **None.** age identity files are just text files (`AGE-SECRET-KEY-1...`). No passphrase prompt, no gpg-agent, no TTY. Fully non-interactive. | +| **Git history** | Encrypted blobs only. The `.sops.yaml` config file (with age recipients) is stored in plaintext in the repo — this is intentional and safe, as public keys are not secrets. | +| **Key sharing** | Age recipients (public keys) can be shared openly. Identity keys (secret keys) must be kept separate from the repo — stored on each machine's filesystem. | +| **Key service** | SOPS supports a local key service (`sops --keyserv`) but it's rarely needed with age since identity files are just files on disk. | + +### Advantages for agent fleets + +- **Fully non-interactive** — no TTY, no passphrase, no agent interaction needed. Age identity is a file. +- **Structural visibility** — encrypted files retain YAML/JSON structure so agents can inspect config shape without decrypting. +- **Multi-recipient** — encrypt to multiple age keys; all fleet machines can decrypt. +- **`sops exec` is agent-safe** — secrets are injected as env vars, never written to stdout or disk. +- **Age keys are tiny and textual** — easy to distribute, no GPG keyring management. + +### Caveats + +- `sops decrypt` stdout leak is a real risk — agents that capture stdout will see plaintext. +- The `.sops.yaml` creation rules file in the repo exposes which age public keys are authorized — harmless but reveals the key set. + +### Agent safety verdict + +**High.** With `sops exec`, secrets never appear in stdout or on disk during agent operation. With `sops decrypt`, plaintext goes to stdout where the agent can read it. Age is fully non-interactive and requires no TTY. + +--- + +## 3. pass (password-store) + age + +**Canonical:** (URL verified: 200) +**Repo:** (URL verified: 200) + +### How it works + +`pass` is a minimal Unix password manager by Jason A. Donenfeld. Each password is a GPG-encrypted file in `~/.password-store/`, versioned in git. The standard tool uses GPG by default. + +### Agent behavior (GPG backend — default) + +| Aspect | Detail | +|--------|--------| +| **Decryption command** | `pass show Path/To/Secret` — outputs password to stdout. | +| **Secret in stdout** | **Yes.** `pass show` outputs plaintext to stdout. Agent sees the secret. | +| **Secret on disk** | Plaintext only transiently in stdout; the encrypted file is on disk. | +| **TTY / unlock needed** | **Yes — GPG agent.** `pass` relies on `gpg-agent` which may require a passphrase prompt (TTY). Without a cached passphrase, the agent will block waiting for interactive input. | +| **Git history** | Encrypted blobs (`.gpg` files). | + +### gopass with age backend + +**Canonical:** (URL verified: 200) + +gopass is a Go reimplementation of `pass` designed for teams. It supports an **age backend** (`gopass config backend set age`) as a drop-in replacement for GPG. + +| Aspect | Detail | +|--------|--------| +| **Decryption** | `gopass show Path/To/Secret` — outputs to stdout. | +| **Secret in stdout** | **Yes.** Same as pass. | +| **TTY / unlock needed** | **No with age backend.** Age identity is a file — no agent/TUI needed. Fully non-interactive. | +| **Git history** | Encrypted blobs (`.age` files). | + +### Agent safety verdict + +**Low (GPG)** / **Moderate (gopass + age)**. GPG requires agent interaction for unlock. gopass + age removes the TTY requirement but plaintext still goes to stdout where the agent can read/copy it. + +--- + +## 4. 1Password CLI + Connect + +**CLI docs:** (URL verified: 200) +**Connect docs:** (URL verified: 200) + +### How it works + +1Password CLI v2 authenticates to 1Password via biometric unlock (`op signin`) or service account tokens. `op connect` runs a local REST API server that CLI tools talk to for vault access. For agent/CI use, 1Password recommends **Service Accounts** and **1Password Environments**. + +### Agent behavior + +| Aspect | Detail | +|--------|--------| +| **Authentication** | `op signin` with username/password **requires biometric unlock** (TTY). Service accounts use tokens and are non-interactive. | +| **Secret retrieval** | `op item get --fields name=password` outputs to stdout. `op eval` or `op run` injects into subprocess env vars. | +| **Secret in stdout** | **Yes** for direct retrieval commands. `op run --env` / `op run --` injects as env vars without stdout exposure. | +| **TTY / unlock needed** | **Personal accounts: YES** (biometric prompt). **Service accounts: NO** (token-based, fully non-interactive). | +| **Requires internet** | **YES.** Requires connection to 1Password Cloud (or self-hosted Connect server for enterprise). | +| **Git history** | N/A — secrets live in 1Password vaults, not in the git repo. No encrypted files in repo. | +| **Cost** | **$36/user/year** (Personal) or **$10/user/month** (Team). Self-hosted Connect requires Business plan. | + +### Agent safety verdict + +**Moderate to High (Service Accounts)** but with significant downsides: requires cloud connectivity, costs money, and personal-account auth requires biometric TTY interaction. Service accounts are designed for CI/CD automation and work headlessly, but they introduce an external dependency and cost that a solo operator on 3 machines may not want. + +--- + +## 5. HashiCorp Vault (AppRole) + +**Docs:** (URL verified: 200) + +### How it works + +Vault is an enterprise secrets management platform. The **AppRole** auth method allows machines to authenticate with Vault using a `role_id` and `secret_id` pair. The recommended token type for AppRole is `batch` — these tokens cannot create child tokens and have a short TTL. + +From the Vault docs: + +> "The approle auth method allows machines or apps to authenticate with Vault-defined roles. ... This auth method is oriented to automated workflows (machines and services), and is less useful for human operators. We recommend using batch tokens with the AppRole auth method." +> +> — Vault AppRole docs, + +### Agent behavior + +| Aspect | Detail | +|--------|--------| +| **Authentication** | Agent calls `vault write auth/approle/login role_id=... secret_id=...` — fully non-interactive. Returns a token. | +| **Secret retrieval** | `vault kv get -field=mysecret secret/myapp` — outputs to stdout. | +| **Secret in stdout** | **Yes.** Direct kv get commands output plaintext to stdout. | +| **Secret on disk** | Vault token can be stored in `$VAULT_TOKEN` env var or file. The token itself is a secret credential. | +| **TTY / unlock needed** | **No.** AppRole login is a simple HTTP POST with role_id + secret_id. | +| **Requires running Vault server** | **Yes.** A Vault server must be running (local or remote) and unsealed. | +| **Git history** | Secrets are stored in Vault's storage backend, not in git. Only the role config lives in version control. | +| **Cost/overhead** | **High.** Requires running a Vault server, configuring auth backends, managing lease renewal, and maintaining the Vault infrastructure. | + +### Agent safety verdict + +**Moderate.** Fully non-interactive and secrets don't live in git. However, it's **overkill for 3 machines** — requires a running Vault server, configuration management, and token lease management. For a solo operator, this is massive operational burden. + +--- + +## 6. systemd credentials + +**Docs:** (URL verified: 200) +**Spec:** (URL verified: 200) + +### How it works + +systemd provides a native credential passing mechanism. The `systemd-creds` tool encrypts credential files with either a TPM2-derived key or a host key stored in `/var/lib/systemd/credential.secret`. Units declare credentials via `LoadCredential=`, `SetCredential=`, or `LoadCredentialEncrypted=`. Decrypted credentials appear as files in `$CREDENTIALS_DIRECTORY` with restricted permissions (0400). + +From the systemd credentials spec: + +> "Service credentials are acquired at the moment of service activation, and released on service deactivation. They are immutable during the service lifetime. Service credentials are accessible to service code as regular files... Unlike environment variables the credential data is not propagated down the process tree." +> +> — systemd.io/CREDENTIALS + +### Agent behavior + +| Aspect | Detail | +|--------|--------| +| **Decryption trigger** | Automatic at service startup. The decrypted credential files appear in `$CREDENTIALS_DIRECTORY` with mode 0400 (owner root only). | +| **Secret on disk** | Plaintext in `$CREDENTIALS_DIRECTORY`. If the agent runs as the service user or root, it can read these files. | +| **Secret in stdout** | **No** — decryption is done by systemd, not by agent-invoked commands. | +| **TTY / unlock needed** | **No.** Decryption is automatic via TPM2 key or host key (`/var/lib/systemd/credential.secret`). | +| **Requires systemd service** | **Yes.** Only works when the agent is running inside a systemd service unit that declares the credentials. | +| **Git history** | Encrypted credential blobs can be stored in git (`LoadCredentialEncrypted=`). No plaintext secrets in history. | +| **Machine-bound** | TPM2-encrypted credentials are bound to the specific machine's TPM. Host-key encrypted credentials are portable but less secure. | +| **Fleet sync** | Encrypted credentials can be pushed to Gitea and decrypted on each machine using each machine's host key or TPM. | + +### Limitations for agent use + +- **Only works for systemd service processes** — the agent must be running as a systemd unit. If you're running agents from a shell session (e.g., Claude Code in ghostty), credentials are not available. +- **Size limited** — credentials are limited-size binary objects (kernel mempage limit). +- **Not for interactive use** — designed for services, not interactive terminal sessions. +- **Encrypted credentials** (`LoadCredentialEncrypted=`) require each target machine to have the decrypting key (TPM2 or host key). + +### Agent safety verdict + +**High (for services)** / **N/A (for interactive shells)**. If your agents run as systemd services, credentials are perfect — decrypted files appear with restricted permissions, no stdout leaks, no TTY. For interactive shell sessions (your current setup), this doesn't apply. + +--- + +## 7. env-file / quarantine pattern + +This is a **pattern**, not a tool. + +### How it works + +1. Store encrypted secrets (e.g., `.env.enc`) in the repo. +2. On each machine, a setup script decrypts them to a **quarantined** location (e.g., `~/.secrets/`) that is **gitignored**. +3. Agents read secrets from the quarantined location. + +### Agent behavior + +| Aspect | Detail | +|--------|--------| +| **Decryption command** | Any tool (`sops decrypt`, `age --decrypt`, `gpg -d`, etc.) run by the user in a script. | +| **Secret in stdout** | Depends on the decryption tool used. With `sops exec` or `age --decrypt -o`, no stdout leak. | +| **Secret on disk** | Plaintext in quarantine dir (`~/.secrets/`) which is gitignored. | +| **TTY / unlock needed** | Depends on decryption backend. Age = no TTY. GPG = TTY needed. | +| **Git history** | Encrypted only. | +| **Fleet sync** | The quarantine directory must be manually synced (e.g., via SSH/rsync) across machines, or each machine must have the decryption key. | + +### Agent safety verdict + +**Flexible but manual.** The pattern itself is sound — quarantined plaintext out of git. But you need a setup script per machine and must coordinate key distribution. + +--- + +## Decision Matrix + +| Tool | Agent-Safe (no stdout leak) | Non-Interactive Unlock | Git-History Safety | Fleet Sync Across 3 Machines | Tooling Burden | +|------|:---:|:---:|:---:|:---:|:---:| +| **git-crypt** | Moderate | GPG: may need TTY | Excellent (encrypted) | Manual (GPG key sharing) | Low-Medium | +| **SOPS + age** | High (with `exec`) | ✅ None | Excellent (encrypted) | ✅ Age key files on each machine | Low | +| **pass (GPG)** | Low (stdout leak) | ❌ GPG agent/TUI | Excellent | Manual (GPG keyring) | Low | +| **gopass + age** | Low (stdout leak) | ✅ None | Excellent (encrypted) | ✅ Age key files on each machine | Low | +| **1Password CLI** | Moderate (stdout leak) | Service acct: ✅ / Personal: ❌ | N/A (cloud) | ✅ Cloud-native | Medium (cost + cloud) | +| **Vault AppRole** | Moderate (stdout leak) | ✅ None | N/A (cloud) | ✅ Cloud-native | High (server) | +| **systemd creds** | ✅ High (for services) | ✅ None | Excellent | Each machine needs key | Medium | +| **env-file quarantine** | Depends on tool | Depends on backend | Encrypted only | Manual sync | Low-Medium | + +--- + +## Recommendation Ranking for This Fleet + +**Fleet profile:** Solo operator, 3 machines (laptop + dankclaw + dankserver), shared git repo pushed to self-hosted Gitea, local LLM agents with shell access. + +### 1. SOPS + age — **Top recommendation** + +**Why:** +- `sops exec` injects secrets as environment variables — **never touches stdout or disk** during agent operation. +- Age identity files are plaintext text files — **zero TTY, zero interactivity**. +- Fully offline — no cloud dependency, no cost. +- `.sops.yaml` creation rules with age recipients are safe in git (public keys only). +- Easy to distribute age key files to all 3 machines. +- Supports YAML, JSON, ENV, INI — covers all config formats. +- CNCF project, actively maintained. + +**Setup:** +```bash +# On each machine: generate age key +age-keygen -o ~/.secrets/agent-age.key + +# Distribute public keys to all machines +age -r -r -r \ + -i ~/.secrets/agent-age.key secrets.yaml > secrets.yaml.sops + +# In .sops.yaml: +creation_rules: + - path_regex: \.sops\.ya?ml$ + key_groups: + - age: + - age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p + - age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg + - age1xk2... +``` + +**Agent workflow:** +```bash +# Agent-safe: secrets in env vars, zero stdout exposure +sops exec --secret-env DB_PASS=secrets.yaml:database.password \ + -- sh -c 'echo "Using DB password from env"' + +# Non-agent-safe (for human use only): stdout leak +sops decrypt secrets.yaml.sops +``` + +### 2. Systemd credentials — **Best for long-running agent services** + +**Why:** +- If agents run as systemd user services, credentials are automatically mounted as restricted files. +- TPM2-bound encryption makes credentials truly machine-specific. +- No decryption commands needed — systemd handles everything at service start. + +**Limitation:** Doesn't work for interactive shell sessions (e.g., Claude Code running in ghostty). + +### 3. env-file quarantine — **Supplementary pattern** + +**Why:** +- Simple, explicit, and works with any encryption backend. +- Gitignored quarantine dir keeps plaintext out of git. +- Good for secrets that need to be written to files (e.g., TLS certs, API key files). + +**Downside:** Requires a setup script per machine and manual key distribution. + +### Not recommended for this fleet + +- **git-crypt:** Works but GPG mode may need TTY. Overkill for a few secret files. No access revocation. +- **pass (GPG):** GPG agent requires TTY — agents will block on passphrase prompts. +- **1Password:** Requires cloud connectivity and paid subscription — unnecessary cost. +- **Vault:** Massive operational overhead for 3 machines. Enterprise solution for a solo operator. + +--- + +## Citations + +- **SOPS homepage:** "Simple And Flexible Tool For Managing Secrets. SOPS encrypts configuration files while keeping the structure visible." — (HTTP 200) +- **SOPS advanced usage:** "Passing Secrets to Other Processes" / `sops exec` — (HTTP 200) +- **SOPS age key management:** "For most use cases, use the Encrypt and Decrypt functions with HybridRecipient and HybridIdentity." — (HTTP 200) +- **age format spec:** "age is a simple, modern and secure file encryption tool, format, and Go library." — (HTTP 200) +- **age official docs:** "age-keygen -o key.txt" / hybrid post-quantum keys — (HTTP 200) +- **pass homepage:** "pass — the standard unix password manager. Each password lives inside of a gpg encrypted file." — (HTTP 200) +- **gopass GitHub:** "The slightly more awesome standard UNIX password manager for teams. Other backends for encryption (e.g. age) and storage (e.g. fossil) are also available." — (HTTP 200) +- **1Password CLI:** "1Password CLI brings 1Password to your terminal. Sign in to 1Password CLI with your fingerprint, and securely access everything you need during development." — (HTTP 200) +- **1Password Connect:** "Use 1Password Connect Server with 1Password CLI to securely access your items in your company's apps and cloud infrastructure using a private REST API." — (HTTP 200) +- **Vault AppRole:** "The approle auth method allows machines or apps to authenticate with Vault-defined roles. This auth method is oriented to automated workflows (machines and services)." — (HTTP 200) +- **systemd-creds man page:** "Credentials are limited-size binary or textual objects that may be passed to unit processes." — (HTTP 200) +- **systemd credentials spec:** "Service credentials are acquired at the moment of service activation, and released on service deactivation. ... Unlike environment variables the credential data is not propagated down the process tree." — (HTTP 200) +- **git-crypt:** "git-crypt enables transparent encryption and decryption of files in a git repository." (v0.8.0, released 2025-09-23) — (HTTP 200) diff --git a/omp-docs/skills/index.md b/omp-docs/skills/index.md new file mode 100644 index 0000000..b7da9a3 --- /dev/null +++ b/omp-docs/skills/index.md @@ -0,0 +1,11 @@ +# Skills Documentation + +Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure, discovery rules, and the pi-package system. + +## Concept Files + +| File | Type | Description | +|------|------|-------------| +| [npx-skills.md](npx-skills.md) | reference | Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure and the pi-package system | +| [vercel-skills.md](vercel-skills.md) | reference | The meta-installer CLI for cross-agent skill distribution, supporting 68+ agents | + diff --git a/omp-docs/skills/npx-skills.md b/omp-docs/skills/npx-skills.md new file mode 100644 index 0000000..a351bc4 --- /dev/null +++ b/omp-docs/skills/npx-skills.md @@ -0,0 +1,164 @@ +--- +type: reference +title: Npx Skills — Distribution and Installation Patterns +description: Distribution and installation patterns for agent skills via npm packages, including SKILL.md structure, discovery rules, and the pi-package system. +tags: + - skills + - npm + - agent-skills + - distribution + - pi-package + - unverified +timestamp: 2026-08-28 +--- + +# Npx Skills — Distribution and Installation + +In the pi coding agent ecosystem, **"npx skills"** refers to the distribution and installation pattern for agent skills through npm packages. Skills are the content (SKILL.md + scripts); pi packages are the delivery mechanism (npm tarball with a `pi` manifest). + +--- + +## The Two-Layer Model + +``` +npm package (tagged pi-package) +├── pi.skills manifest → points to ./skills/ +└── skills/ + ├── brave-search/SKILL.md + ├── browser-tools/SKILL.md + └── tdd-workflow/SKILL.md +``` + +--- + +## The Agent Skills Specification + +Pi implements the [Agent Skills standard](https://agentskills.io), which defines: + +- A **frontmatter block** (YAML) at the top of `SKILL.md` with required `name` and `description` fields +- A **Markdown body** with the skill's instructions +- Optional subdirectories: `scripts/`, `references/`, `assets/` + +The specification is **cross-agent-compatible**: skills written for pi work with Claude Code, Codex CLI, Amp, Droid, and others. + +--- + +## How Skills Work in Pi + +1. **At startup**, pi scans all configured skill locations and extracts skill names and descriptions +2. **The system prompt** includes available skills in XML format +3. **When a task matches**, the agent uses `read` to load the full SKILL.md +4. **The agent follows the instructions**, using relative paths to reference scripts and assets + +This is **progressive disclosure**: only descriptions are always in context, full instructions load on-demand. + +--- + +## Installing Skills via NPM / Npx + +### Method 1: Direct `pi install` (recommended) + +```bash +pi install npm:pi-web-access +pi install npm:@anton-kochev/pi-skills +pi install npm:bigpowers +pi install npm:@monopi/skills +``` + +### Method 2: Npx-based setup tools + +```bash +npx @monopi/monopi # One-command setup +npx @monopi/monopi --version 0.2.13 # Pin a version +npx @monopi/monopi --local # Project-local install +``` + +### Method 3: Manual clone (git repos) + +```bash +git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills +``` + +--- + +## Pi Packages + +### Package Structure + +``` +my-pi-package/ +├── package.json # npm metadata + pi manifest +├── skills/ # Conventional directory (auto-discovered) +│ ├── my-skill/ +│ │ └── SKILL.md +├── extensions/ # TypeScript extensions +├── prompts/ # Prompt templates +└── themes/ # TUI themes +``` + +### package.json with pi Manifest + +```json +{ + "name": "my-pi-package", + "keywords": ["pi-package"], + "pi": { + "extensions": ["./extensions"], + "skills": ["./skills"], + "prompts": ["./prompts"], + "themes": ["./themes"] + } +} +``` + +### Package Sources + +| Source Type | Example | Notes | +|-------------|---------|-------| +| **npm** | `npm:@foo/bar@1.0.0` | Pinned versions, installed to `~/.pi/agent/npm/` | +| **git** | `git:github.com/user/repo@v1` | Pinned to tags/commits, cloned to `~/.pi/agent/git/` | +| **local** | `./relative/path` | Points to local directory, added without copying | + +--- + +## SKILL.md Frontmatter + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | **Yes** | Max 64 chars. Lowercase a-z, 0-9, hyphens only. | +| `description` | **Yes** | Max 1024 chars. What the skill does and when to use it. | +| `license` | No | License name or reference to bundled file. | +| `compatibility` | No | Max 500 chars. Environment requirements. | +| `metadata` | No | Arbitrary key-value mapping. | +| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). | +| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. | + +**The description determines when the agent loads the skill. Be specific.** + +--- + +## Discovery Rules + +| Location | Scope | Rule | +|----------|-------|------| +| `~/.pi/agent/skills/` | All projects | Direct root `.md` files + directories with `SKILL.md` | +| `.pi/skills/` | Current project | Direct root `.md` files + directories with `SKILL.md` | +| `~/.agents/skills/` | All projects | Only directories with `SKILL.md` (root `.md` ignored) | + +--- + +## Skills vs Extensions + +| Feature | Skills | Extensions | +|---------|--------|------------| +| **Format** | Markdown (`SKILL.md`) | TypeScript (`.ts`) | +| **Purpose** | Instructions for the LLM | Code that intercepts events | +| **Execution** | Agent reads and follows | Runs in pi's Node.js runtime | +| **Loading** | On-demand | Always loaded at startup | + +--- + +## Cross-References + +- See [Vercel `skills` CLI](vercel-skills.md) for the meta-installer tool. +- The [Agent Skills specification](https://agentskills.io/specification) is the canonical format. diff --git a/omp-docs/skills/vercel-skills.md b/omp-docs/skills/vercel-skills.md new file mode 100644 index 0000000..11c8f84 --- /dev/null +++ b/omp-docs/skills/vercel-skills.md @@ -0,0 +1,166 @@ +--- +type: reference +title: Vercel Labs `skills` CLI +description: The meta-installer CLI for cross-agent skill distribution, supporting 68+ agents with add/use/find/list/update/remove commands. +tags: + - skills + - vercel + - meta-installer + - cross-agent + - cli + - unverified +timestamp: 2026-08-28 +--- + +# Vercel Labs `skills` CLI + +`skills` is the CLI for the open agent skills ecosystem, created by Gunnar (@rauchg) at Vercel. It is a **meta-installer** that downloads skills from repositories and installs them into 68+ supported coding agents' skill directories. + +**Repository:** [vercel-labs/skills](https://github.com/vercel-labs/skills) +**Specification:** [Agent Skills](https://agentskills.io) + +--- + +## Installation + +No global installation needed — run directly via `npx`: + +```bash +npx skills add vercel-labs/agent-skills # Install from GitHub +npx skills add vercel-labs/agent-skills --list # List without installing +npx skills use vercel-labs/agent-skills@skill-name # Use without installing +npx skills find typescript # Search +``` + +--- + +## Commands + +### `skills add` — Install Skills + +```bash +npx skills add [options] +``` + +| Option | Description | +|--------|-------------| +| `-g, --global` | Install to user directory (`~/`) | +| `-a, --agent ` | Target specific agents | +| `-s, --skill ` | Install specific skills (use `'*'` for all) | +| `-l, --list` | List available skills | +| `--copy` | Copy files instead of symlinking | +| `-y, --yes` | Skip confirmation prompts | +| `--all` | Install all to all agents | + +### `skills use` — Use Without Installing + +```bash +npx skills use [options] +# Generates prompt to stdout, or launches agent with --agent +``` + +### `skills list` (alias: `ls`) + +```bash +npx skills list # All installed skills +npx skills ls -g # Global only +``` + +### `skills find` — Search + +```bash +npx skills find # Interactive search +npx skills find typescript # By keyword +``` + +### `skills update` + +```bash +npx skills update # Update all (interactive) +npx skills update -g # Global only +npx skills update -y # Auto-detect scope +``` + +### `skills remove` (alias: `rm`) + +```bash +npx skills remove # Interactive +npx skills remove my-skill -a claude-code -g +npx skills remove --all # Remove everything +``` + +### `skills init` — Create Template + +```bash +npx skills init # Current directory +npx skills init my-skill # Subdirectory +``` + +--- + +## Source Formats + +```bash +npx skills add owner/repo # GitHub shorthand +npx skills add https://github.com/owner/repo # Full URL +npx skills add https://gitlab.com/org/repo # GitLab +npx skills add git@github.com:owner/repo.git # Git URL +npx skills add ./my-local-skills # Local path +``` + +--- + +## Installation Scope + +| Scope | Flag | Location | Use Case | +|-------|------|----------|----------| +| **Project** | _(default)_ | `.//skills/` | Committed with project | +| **Global** | `-g` | `~//skills/` | All projects | + +Symlink (recommended) or copy mode. + +--- + +## Agent Support + +The CLI supports **68+ agents**. Key ones: + +| Agent | `--agent` | Project Path | Global Path | +|-------|-----------|--------------|-------------| +| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` | +| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` | +| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` | +| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` | +| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` | +| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` | +| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` | + +Full table available in the [source repository](https://github.com/vercel-labs/skills). + +--- + +## Lock File System + +| Type | Path | Scope | +|------|------|-------| +| **Global lock** | `~/.agents/.skill-lock.json` | User-wide | +| **Local lock** | `skills-lock.json` | Project (check in) | + +`skills check` compares GitHub tree SHA with the lock file. `skills update` reinstalls changed skills. + +--- + +## Environment Variables + +| Variable | Description | +|----------|-------------| +| `INSTALL_INTERNAL_SKILLS` | Set to `1` to show skills marked `internal: true` | +| `DISABLE_TELEMETRY` | Disable anonymous usage telemetry | +| `DO_NOT_TRACK` | Alternative way to disable telemetry | + +--- + +## Cross-References + +- See [Npx Skills](npx-skills.md) for the pi-specific npm package distribution system. +- The [Agent Skills specification](https://agentskills.io/specification) is the shared standard. diff --git a/omp-docs/system/dankclaw.md b/omp-docs/system/dankclaw.md new file mode 100644 index 0000000..8a7c77b --- /dev/null +++ b/omp-docs/system/dankclaw.md @@ -0,0 +1,83 @@ +--- +type: reference +title: Dankclaw +description: Secondary inference server at 192.168.0.143. Runs llama.cpp (frank-default-large). +tags: + - network + - llamacpp + - inference + - server + - comfyui + - unverified +generated: + by: chief-designer/agent + at: 2026-08-26T00:00:00Z +verified: 2026-08-28 +--- + +# Dankclaw + +Secondary llama.cpp inference server for the Frank Program. Serves larger models used by planner, worker, reviewer, oracle, and context-builder subagents. + +## Connection Details + +| Property | Value | +|----------|-------| +| **Hostname** | dankclaw | +| **IP Address** | 192.168.0.143 | +| **Port** | 7770 | +| **Base URL** | `http://192.168.0.143:7770/v1` | +| **API** | OpenAI-compatible completions | +| **Authentication** | API key configured | + +## Models + +| Model ID | Context Window | Reasoning | Input Types | +|----------|---------------|-----------|-------------| +| `frank-default-large` | 262,144 tokens | Yes | Text, *Image* (unverified) | + +## Services + +### llama.cpp + +| Property | Value | +|----------|-------| +| **Port** | 7770 | +| **Models** | `frank-default-large` | + +## Hardware + +| Property | Value | +|----------|-------| +| **CPU** | AMD Ryzen AI MAX+ 395 (16C/16T, Strix Halo) | +| **GPU** | Radeon 8060S integrated (gfx1151, amdgpu) | +| **RAM** | 119 GiB | +| **Storage** | Kingston SNV3S1000G NVMe (931.5 GB), ~676 GB free | +| **OS** | Ubuntu 26.04 LTS, kernel 7.0.0-30-generic | +| **ROCm** | 7.2.4 (driver: 7.0.0-30-generic) | +| **Python** | 3.14.4 (system) | + +## Usage + +Dankclaw handles complex tasks delegated by subagent overrides. The `frank-default-large` model provides extended context. *Multimodal input support is unverified.* + +```bash +# Health check +curl http://192.168.0.143:7770/health + +# Test with large model +curl http://192.168.0.143:7770/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer " \ + -d '{"model":"frank-default-large","messages":[{"role":"user","content":"Hello"}],"max_tokens":32}' +``` + +## Related Knowledge Bases (sibling project on dankware) + +- **serverAppConfigs** — `/home/dank/Projects/serverAppConfigs/` — Podman deployment config for this host (AI, search, development, observability stack, incl. the Hermes compose service) **plus the LLM inference fleet** (frank-default-large, CIRU ROCmFPX llama.cpp, :7770). The former `vllmScripts` repo merged into it on 2026-08-22 (history preserved). Start at `/home/dank/Projects/serverAppConfigs/docs/index.md` (see `dankclaw/compose.yaml` + `docs/Dankclaw/`; LLM fleet at `docs/LLM/index.md`, deploy runbook at `docs/LLM/deployment.md`). + +## See Also + +- [[models|models]] — Provider definitions +- [[dankserver|dankserver]] — Primary server +- [[network|network]] — Network topology diff --git a/omp-docs/system/dankserver.md b/omp-docs/system/dankserver.md new file mode 100644 index 0000000..b24369e --- /dev/null +++ b/omp-docs/system/dankserver.md @@ -0,0 +1,75 @@ +--- +type: reference +title: Dankserver +description: Primary llama.cpp inference server at 192.168.0.235:7770, serving frank-default-small with 163,840-token context window. +tags: + - network + - llamacpp + - inference + - server + - unverified +generated: + by: chief-designer/agent +verified: 2026-08-28 +status: stable +--- + +# Dankserver + +Primary llama.cpp inference server for the Frank Program. Serves `frank-default-small` — a fast, capable model with image support. + +## Connection Details + +| Property | Value | +|----------|-------| +| **Hostname** | dankserver | +| **IP Address** | 192.168.0.235 | +| **Port** | 7770 | +| **Base URL** | `http://192.168.0.235:7770/v1` | +| **API** | OpenAI-compatible completions | +| **Authentication** | None | + +## Model + +| Property | Value | +|----------|-------| +| **Model ID** | `frank-default-small` | +| **Context Window** | 163,840 tokens | +| **Reasoning** | Supported | +| **Input Types** | Text, *Image* (unverified) | + +## Usage + +Dankserver serves the small subagent model `frank-default-small`. Small subagent roles route here unless a role override picks a different model. + +```bash +# Health check +curl http://192.168.0.235:7770/health + +# Quick test +curl http://192.168.0.235:7770/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{"model":"frank-default-small","messages":[{"role":"user","content":"Hello"}],"max_tokens":32}' +``` + +## Hardware + +| Property | Value | +|----------|-------| +| **CPU** | AMD Ryzen 7 7700X (8C/16T, Raphael) | +| **GPU** | NVIDIA GeForce RTX 3090 (24 GiB VRAM, EVGA) | +| **RAM** | 60 GiB | +| **Swap** | 64 GiB (/swapfile) | +| **Storage** | Kingston SNV3S1000G NVMe (931.5 GB) + md0 RAID (6×18.2T Toshiba, /mnt/entropy, 91T) | +| **OS** | Ubuntu 26.04 LTS, kernel 7.0.0-30-generic | +| **NVIDIA Driver** | 595.84 | + +## Related Knowledge Bases (sibling project on dankware) + +- **serverAppConfigs** — `/home/dank/Projects/serverAppConfigs/` — Podman deployment config for this host (media and library stack: RomM, Copyparty, Calibre-Web) **plus the LLM inference fleet** (frank-default-small, llama.cpp, :7770). The former `vllmScripts` repo merged into it on 2026-08-22 (history preserved). Start at `/home/dank/Projects/serverAppConfigs/docs/index.md` (see `dankserver/compose.yaml` + `docs/Dankserver/`; LLM fleet at `docs/LLM/index.md`, deploy runbook at `docs/LLM/deployment.md`). + +## See Also + +- [[models|models]] — Provider definitions +- [[dankclaw|dankclaw]] — Secondary server +- [[network|network]] — Network topology diff --git a/omp-docs/system/dankware/displays.md b/omp-docs/system/dankware/displays.md new file mode 100644 index 0000000..e724b92 --- /dev/null +++ b/omp-docs/system/dankware/displays.md @@ -0,0 +1,123 @@ +--- +type: reference +title: Display Configuration +description: Three-monitor display setup on dankware — dual Samsung Odyssey G75F (portrait) and internal BOE panel. +tags: + - display + - monitors + - niri + - unverified +generated: + by: chief-designer/agent + at: 2026-08-26T00:00:00Z +status: stable +verified: 2026-08-28 + +# Display Configuration — dankware + +Three displays in a horizontal arrangement. Two external Samsung Odyssey G75F monitors in portrait orientation flank the internal laptop panel. + +--- + +## Layout + +``` +┌──────────────┬──────────────┬──────────────┐ +│ │ │ │ +│ DP-1 │ DP-3 │ eDP-1 │ +│ Samsung │ Samsung │ BOE │ +│ 1920x1200 │ 1920x1200 │ 2560x1600 │ +│ Portrait │ Portrait │ Landscape │ +│ 90° rotate │ 270° rotate │ 1.5x scale │ +│ │ │ │ +└──────────────┴──────────────┴──────────────┘ + x=0,0 x=1200,0 auto-placed +``` + +--- + +## Display Specifications + +### DP-1 — Samsung Odyssey G75F (Left) + +| Property | Value | +|----------|-------| +| **Make** | Samsung Electric Company | +| **Model** | Odyssey G75F HNTY601056 | +| **Resolution** | 1920x1200 @ 59.95 Hz (preferred) | +| **Transform** | 90° (portrait) | +| **Position** | x=0, y=0 | +| **Scale** | 1.0 | + +### DP-3 — Samsung Odyssey G75F (Center) + +| Property | Value | +|----------|-------| +| **Make** | PNP(XYM) | +| **Model** | PM1601 | +| **Resolution** | 1920x1200 @ 59.95 Hz (preferred) | +| **Transform** | 270° (portrait) | +| **Position** | x=1200, y=0 | +| **Scale** | 1.0 | + +### eDP-1 — Internal BOE Panel (Right) + +| Property | Value | +|----------|-------| +| **Make** | BOE | +| **Model** | 0x0C06 | +| **Resolution** | 2560x1600 @ 240 Hz (preferred) | +| **Transform** | normal (landscape) | +| **Position** | auto-placed | +| **Scale** | 1.5 | +| **Physical Size** | 340x220 mm | + +--- + +## Niri Configuration + +**File:** `~/.config/niri/cfg/display.kdl` + +```kdl +output "Samsung Electric Company Odyssey G75F HNTY601056" { + mode "3840x2160@60" + scale 1 + transform "normal" + position x=0 y=0 +} + +output "DP-1" { + transform "90" + position x=0 y=0 +} + +output "DP-3" { + transform "270" + position x=1200 y=0 +} + +output "eDP-1" { + // no position - auto-placed to the right of DP-* outputs +} +``` + +--- + +## GPU Assignment + +The Intel Arc iGPU handles display output. The render node is explicitly assigned: + +```kdl +// In ~/.config/niri/cfg/misc.kdl +environment { + render-node "/dev/dri/renderD129" // Intel Arc iGPU +} +``` + +The NVIDIA RTX 4070 Mobile is available for compute tasks but does not drive displays. + +--- + +## See Also + +- [niri](../../tools/niri/index.md) — Compositor configuration + full niri config breakdown diff --git a/omp-docs/system/dankware/hardware.md b/omp-docs/system/dankware/hardware.md new file mode 100644 index 0000000..279ed74 --- /dev/null +++ b/omp-docs/system/dankware/hardware.md @@ -0,0 +1,106 @@ +--- +type: reference +title: Hardware Specifications +description: Complete hardware specifications for dankware — Alienware m16 R2. +tags: + - hardware + - alienware + - specifications + - unverified +generated: + by: chief-designer/agent + at: 2026-08-26T00:00:00Z +verified: 2026-08-28 +--- + +# Hardware Specifications — dankware + +## System + +| Property | Value | +|----------|-------| +| **Manufacturer** | Alienware | +| **Model** | Alienware m16 R2 | +| **BIOS Vendor** | Alienware | + +## Processor + +| Property | Value | +|----------|-------| +| **Model** | Intel Core Ultra 7 155H | +| **Architecture** | Meteor Lake (6p+8e cores) | +| **Threads** | 22 | +| **Architecture** | x86_64 | + +## Graphics + +| Device | PCI Address | Details | +|--------|-------------|---------| +| **Intel Arc** | `00:02.0` | Meteor Lake-P [Intel Arc Graphics] (rev 08) | +| **NVIDIA RTX 4070 Mobile** | `01:00.0` | AD106M [GeForce RTX 4070 Max-Q / Mobile] (rev a1) | +| **NVIDIA Audio** | `01:00.1` | AD106M High Definition Audio Controller | + +**NVIDIA Driver:** 610.57.04 + +## Accelerators + +| Device | PCI Address | Details | +|--------|-------------|---------| +| **NPU** | `00:0b.0` | Core Ultra 200H/200V Series NPU (rev 04) | +| **GNNA** | `00:08.0` | Meteor Lake-P Gaussian & Neural-Network Accelerator | +| **DTT** | `00:04.0` | Dynamic Tuning Technology | + +## Memory + +| Type | Size | Notes | +|------|------|-------| +| **RAM** | 62 GiB | System memory | +| **Swap** | 62 GiB | zram0 (compressed RAM swap) | + +## Storage + +| Device | Model | Size | Mount | +| **nvme0n1** | Samsung 990 EVO (2TB) | 1.8 TB | LUKS encrypted, `/` (4G boot, 1.8T root) | +**Root filesystem:** 1.8 TB total, ~1.2 TB available (~39% used). + +## USB and Thunderbolt + +| Device | PCI Address | Details | +|--------|-------------|---------| +| **USB xHCI** | `00:0d.0` | Core Ultra 200 Series USB xHCI | +| **Thunderbolt DMA** | `00:0d.3` | Core Ultra 200 Series Thunderbolt DMA1 | +| **USB 3.2** | `00:14.0` | Meteor Lake-P USB 3.2 Gen 2x1 xHCI | + +## Network + +| Device | Details | +| **Wi-Fi** | wlan0 — Intel Wi-Fi 7 BE202 (AX1775*) — connected to FRANKFI-5G (192.168.0.12/24) | +| **USB Ethernet** | enp0s13f0u1u1 — no carrier | +| **Built-in Ethernet** | enp47s0 (Killer E3000 2.5GbE) — UP, 192.168.0.226/24 | + +## Other + +| Device | PCI Address | Details | +|--------|-------------|---------| +| **Audio** | `00:1f.3` | Meteor Lake-P HD Audio Controller | +| **Card Reader** | `2e:00.0` | Realtek RTS525A PCIe Card Reader | +| **Sensor Hub** | `00:12.0` | Meteor Lake-P Integrated Sensor Hub | +| **CSME HECI** | `00:16.0` | Meteor Lake-P CSME HECI | +| **SMBus** | `00:1f.4` | Meteor Lake-P SMBus Controller | + +--- + +## PCI Summary + +``` +├── Intel Host Bridge/DRAM (00:00.0) +├── Intel Arc Graphics (00:02.0) ──── iGPU +├── NVIDIA RTX 4070 Mobile (01:00.0) ── dGPU +├── Intel NPU (00:0b.0) ──── AI acceleration +├── Intel GNNA (00:08.0) ─── AI acceleration +├── Samsung NVMe PM9C1a (02:00.0) ── primary SSD (/ + /boot) +├── KIOXIA NVMe BG6 (2d:00.0) ── secondary SSD +├── Killer E3000 2.5GbE (2f:00.0) ── built-in Ethernet +├── Intel Wi-Fi 7 BE202 (30:00.0) ── Wi-Fi +└── Realtek Card Reader (2e:00.0) +``` diff --git a/omp-docs/system/dankware/index.md b/omp-docs/system/dankware/index.md new file mode 100644 index 0000000..6acbb9b --- /dev/null +++ b/omp-docs/system/dankware/index.md @@ -0,0 +1,86 @@ +# System Overview — dankware + +**dankware** is an Alienware m16 R2 laptop. It runs CachyOS Linux with the Niri scrollable-tiling Wayland compositor and Noctalia Shell. It serves as the primary workstation for the Frank Program, running the pi coding agent locally and connecting to remote llama.cpp servers. + +--- + +## Quick Facts + +| Property | Value | +|----------|-------| +| **Hostname** | `dankware` | +| **System** | Alienware m16 R2 | +| **OS** | CachyOS (Arch-based rolling) | +| **Kernel** | `linux-cachyos 7.2.0-1` (EEVDF + LTO + AutoFDO + Propeller) | +| **LTS Kernel** | `linux-cachyos-lts 6.18.42-1` | +| **Desktop** | Niri 26.04 (Wayland) | +| **Shell** | Noctalia Shell 4.7.7 | +| **Terminal** | Ghostty 1.3.1 | +| **Shell (CLI)** | zsh (fish also installed) | +| **Display Manager** | SDDM | +| **Bootloader** | GRUB | +| **Init** | systemd (graphical.target) | + +--- + +## Hardware Summary + +| Component | Specification | +|-----------|---------------| +| **CPU** | Intel Core Ultra 7 155H (Meteor Lake, 22 threads) | +| **iGPU** | Intel Arc Graphics (Meteor Lake-P) | +| **dGPU** | NVIDIA GeForce RTX 4070 Laptop (AD106M, Max-Q) | +| **NVIDIA Driver** | 610.57.04 | +| **RAM** | 62 GiB | +| **Swap** | 62 GiB (zram0) | +| **Boot Disk** | Samsung 990 EVO (1.8 TB), /boot + LUKS-encrypted / | +| **Secondary Disk** | KIOXIA BG6 (953.9 GB) | +| **Root** | LUKS encrypted, ~1.2 TB available | + +--- + +## Software Stack + +### Compositor and Shell + +- **Niri 26.04** — Scrollable-tiling Wayland compositor +- **Noctalia Shell 4.7.7** — Desktop shell built with Quickshell (qs 0.0.12) +- **Shelly Notifications** — Notification tray service + +### Applications + +- **Ghostty 1.3.1** — Terminal emulator +- **Firefox 153.0** — Primary browser +- **Chromium 150.0** — Secondary browser +- **Nautilus 50.2.2** — File manager +- **Neovim 0.12.4** — Text editor +- **Steam 1.0.0.86** — Gaming platform + +### Audio + +- **PipeWire 1.6.8** — Multimedia router +- **WirePlumber 0.5.15** — Session manager +- **pavucontrol** — Volume control GUI + +### Screenshots and Recording + +- **grim** — Wayland screenshot utility +- **slurp** — Screen region selector +- **swappy** —Screenshot annotator +- **wl-clipboard 2.3.0** — Wayland clipboard +- **hyprpicker** — Color picker +- **wf-recorder** — Screen recording + +### Display Management + +- **wlr-randr** — Display configuration utility + +See [[hardware|hardware]] for full hardware details. +See [[displays|displays]] for the three-monitor layout. +See [[cachyos|cachyos]] for operating system details. + + * [Display Configuration](displays.md) — Three-monitor display setup on dankware — dual Samsung Odyssey G75F (portrait) and internal BOE panel. + + * [Hardware Specifications](hardware.md) — Complete hardware specifications for dankware — Alienware m16 R2. + + * [Network Interfaces](network.md) — Network configuration for dankware — Wi-Fi, USB Ethernet, and local network topology. diff --git a/omp-docs/system/dankware/network.md b/omp-docs/system/dankware/network.md new file mode 100644 index 0000000..b03fd57 --- /dev/null +++ b/omp-docs/system/dankware/network.md @@ -0,0 +1,54 @@ +--- +type: reference +title: Network Interfaces +description: Network configuration for dankware — Wi-Fi, USB Ethernet, and local network topology. +tags: + - network + - interfaces + - wifi + - unverified +generated: + by: chief-designer/agent + at: 2026-08-26T00:00:00Z +verified: 2026-08-28 +--- + +# Network Interfaces — dankware + +## Active Interfaces + +| Interface | Type | Status | Address | Connection | +| `wlan0` | Wi-Fi | Connected | 192.168.0.12/24 | FRANKFI-5G | +| `enp0s13f0u1u1` | USB Ethernet | Down (no carrier) | — | — | +| `enp47s0` | Built-in Ethernet (Killer E3000) | Connected | 192.168.0.226/24 | Wired connection 1 | +| `lo` | Loopback | Connected | 127.0.0.1/8 | lo | + +## Network Manager + +| Property | Value | +|----------|-------| +| **Tool** | nmcli 1.58.0 | +| **DNS** | systemd-resolved (127.0.0.53) | +| **mDNS** | Enabled (resolve) | + +## Local Network + +| Host | IP | Service | Port | +| **dankware** | 192.168.0.12 (Wi-Fi) / 192.168.0.226 (Built-in Eth) | This machine | — | +| **dankserver** | 192.168.0.235 | llama.cpp | 7770 | +| **dankclaw** | 192.168.0.143 | llama.cpp | 7770 | + +## Services + +| Service | Status | +|---------|--------| +| **sshd** | Active | +| **bluetooth** | Active (BlueZ 5.87) | + +--- + +## See Also + +- [[dankserver|dankserver]] — Primary llama.cpp server +- [[dankclaw|dankclaw]] — Secondary llama.cpp server +- ](../index.md) — System overview diff --git a/omp-docs/system/index.md b/omp-docs/system/index.md new file mode 100644 index 0000000..a006c22 --- /dev/null +++ b/omp-docs/system/index.md @@ -0,0 +1,52 @@ +# System Documentation + +Hardware, operating system, and network documentation for the Frank Program +infrastructure. dankware is the primary workstation; Dankserver and Dankclaw are +the llama.cpp inference servers it talks to. + +## Local System + +- [System Overview](/system/dankware/index.md) — dankware: Alienware m16 R2 laptop running CachyOS with Niri Wayland. +- [Hardware Specifications](/system/dankware/hardware.md) — CPU, GPU, memory, storage, network controllers, and PCI devices for dankware. +- [Display Configuration](/system/dankware/displays.md) — Three-monitor setup: dual Samsung Odyssey G75F (portrait) plus the internal BOE panel. +- [Network Interfaces](/system/dankware/network.md) — Wi-Fi (Intel BE202), built-in Ethernet (Killer E3000), USB Ethernet, and local network topology. + +## Network Systems + +- [Dankserver](/system/dankserver.md) — Primary llama.cpp inference server at 192.168.0.235:7770, serving `frank-default-small` (163,840-token context). AMD Ryzen 7 7700X, RTX 3090, Ubuntu 26.04. +- [Dankclaw](/system/dankclaw.md) — Secondary inference server at 192.168.0.143:7770, serving `frank-default-large` (262,144-token context). AMD Ryzen AI MAX+ 395 (Strix Halo), Ubuntu 26.04, ROCm. + +## Infrastructure Diagram + +```mermaid +graph TB + subgraph Local[dankware - Alienware m16 R2] + A[Niri Wayland] + B[Noctalia Shell] + C[Ghostty Terminal] + D[Pi Agent] + end + + subgraph Network[192.168.0.0/24] + E[dankserver
192.168.0.235:7770
frank-default-small] + F[dankclaw
192.168.0.143:7770
frank-default-large] + end + + D --> E + D --> F + C --> D + B --> C + A --> B +``` + +## Related Knowledge Bases (sibling projects on dankware) + +The fleet has one sibling OKF knowledge base outside this bundle. Read it for +deployment and inference details. This bundle links to it from the server pages. + +* **serverAppConfigs** — `/home/dank/Projects/serverAppConfigs/` (index: `/home/dank/Projects/serverAppConfigs/docs/index.md`). Podman deployment configuration for both servers: compose files, Caddy reverse proxy, deploy scripts, bats tests, and the Obsidian-vault service docs (Dankclaw, Dankserver, Architecture, Infrastructure) — **plus the LLM inference fleet** (merged from the former `vllmScripts` repo on 2026-08-22, history preserved): llama.cpp on Dankserver (:7770, `frank-default-small`) and CIRU ROCmFPX llama.cpp on Dankclaw (:7770, `frank-default-large`). LLM fleet docs: `docs/LLM/index.md`; deploy runbook: `docs/LLM/deployment.md`. + +## Related + +- [Root Index](/index.md) — bundle navigation. +- [Engineering](/engineering/index.md) — best practices behind the ops. diff --git a/omp-docs/tools/applications.md b/omp-docs/tools/applications.md new file mode 100644 index 0000000..8dd7ae4 --- /dev/null +++ b/omp-docs/tools/applications.md @@ -0,0 +1,77 @@ +--- +type: index +title: Default Applications +description: Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming. +tags: + - applications + - cachyos + - niri + - userspace + - index +timestamp: 2026-08-06 +--- + +# Default Applications + +Applications that ship with or are configured on CachyOS with Niri on dankware. + +## Core Applications + +| Application | Version | Purpose | +|-------------|---------|---------| +| ](ghostty/index.md) | 1.3.1 | Terminal emulator | +| **Firefox** | 153.0 | Primary browser | +| **Chromium** | 150.0 | Secondary browser | +| **Nautilus** | 50.2.2 | File manager | +| **Neovim** | 0.12.4 | Text editor | +| **Steam** | 1.0.0.86 | Gaming platform | + +## System Utilities + +| Application | Version | Purpose | +|-------------|---------|---------| +| **Noctalia Shell** | 4.7.7 | Desktop shell (launcher, wallpaper, session menu) | +| **Shelly Notifications** | — | Notification daemon | +| **pavucontrol** | — | Audio mixer | +| **wlr-randr** | — | Display management | + +## Screenshot and Recording + +| Application | Purpose | +|-------------|---------| +| **grim** | Wayland screenshot | +| **slurp** | Region selector | +| **swappy** | Screenshot annotator | +| **wf-recorder** | Screen recording | +| **hyprpicker** | Color picker | +| **wl-clipboard** | Wayland clipboard | + +## Audio + +| Application | Version | Purpose | +|-------------|---------|---------| +| **PipeWire** | 1.6.8 | Multimedia router | +| **WirePlumber** | 0.5.15 | Session manager | + +--- + +## Workflow + +```mermaid +graph LR + A[Noctalia Shell] --> B[Mod+Return
Ghostty] + A --> C[Mod+CTRL+Return
Launcher] + A --> D[Mod+B
Firefox] + A --> E[Mod+E
Nautilus] + A --> F[Mod+ALT+L
Lock] + A --> G[Mod+Shift+Q
Session] +``` + +--- + +## See Also + +- [[cachyos|cachyos]] — Operating system documentation +- [[noctalia-shell|noctalia-shell]] — Desktop shell +- [niri](niri/index.md) — Compositor +- ](ghostty/index.md) — Terminal configuration diff --git a/omp-docs/tools/cachyos.md b/omp-docs/tools/cachyos.md new file mode 100644 index 0000000..c36f0c6 --- /dev/null +++ b/omp-docs/tools/cachyos.md @@ -0,0 +1,112 @@ +--- +type: reference +title: CachyOS +description: Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on dankware. +tags: + - cachyos + - arch + - linux + - kernel + - performance +timestamp: 2026-08-06 +--- + +# CachyOS + +CachyOS is an Arch Linux-based rolling release distribution focused on performance. It ships with custom kernels featuring the EEVDF scheduler, LTO compilation, AutoFDO profiling, and Propeller scheduling patches. + +--- + +## System Information + +| Property | Value | +|----------|-------| +| **OS** | CachyOS (rolling) | +| **Kernel** | `linux-cachyos 7.1.4-1` | +| **LTS Kernel** | `linux-cachyos-lts 6.18.38-2` | +| **Package Manager** | pacman | +| **Init** | systemd | +| **Display Manager** | SDDM | + +## Kernel Features + +The CachyOS kernel includes: + +- **EEVDF Scheduler** — Earliest Eligible Virtual Deadline First, successor to CFS +- **LTO** — Link-Time Optimization for better code generation +- **AutoFDO** — Auto Feedback-Directed Optimization from profiling data +- **Propeller Scheduling** — Reduced latency scheduling patches + +## Repositories + +CachyOS uses v3 repositories alongside standard Arch repos: + +| Repository | Purpose | +|------------|---------| +| `[cachyos-v3]` | CachyOS-specific packages (kernels, tools) | +| `[cachyos-extra-v3]` | CachyOS extra packages | +| `[cachyos-core-v3]` | CachyOS core packages | +| `[cachyos]` | Legacy CachyOS repo | +| `[core]` | Arch core | +| `[extra]` | Arch extra | +| `[multilib]` | 32-bit compatibility | + +## CachyOS-Specific Packages + +| Package | Description | +|---------|-------------| +| `cachyos-kernel-manager` | Simple kernel manager (1.19.0) | +| `cachyos-hello` | Welcome screen (0.26.0) | +| `cachyos-gaming-meta` | Gaming dependencies meta-package | +| `cachyos-gaming-applications` | Common gaming applications | +| `cachyos-ananicy-rules` | Process auto-categorization rules | +| `cachyos-fish-config` | Fish shell configuration | +| `cachyos-alacritty-config` | Alacritty terminal config | +| `cachyos-hooks` | libalpm hooks | +| `cachyos-micro-settings` | Micro settings utility | + +## Gaming Stack + +CachyOS ships with a comprehensive gaming stack: + +- **Proton-CachyOS-SLR** — Proton with Same-Level-Root patches +- **Wine-CachyOS-Opt** — Optimized Wine build +- **UMU Launcher** — Universal Minecraft/Unity launcher +- **ProtonTricks / Winetricks** — Wine configuration utilities +- **Vulkan Tools** — Vulkan validation and utilities +- **32-bit libraries** — Full lib32 support for Steam + +## Default Userspace + +CachyOS with Niri ships with a curated set of applications: + +- **Niri** — Scrollable-tiling Wayland compositor +- **Noctalia Shell** — Desktop shell (launcher, wallpaper, session menu, lock screen) +- **Shelly Notifications** — Notification daemon +- **Ghostty** — Terminal emulator +- **Firefox** — Web browser +- **Chromium** — Alternative browser +- **Nautilus** — File manager +- **Neovim** — Text editor +- **Steam** — Gaming platform +- **PipeWire + WirePlumber** — Audio +- **grim/slurp/swappy** — Screenshots +- **wf-recorder** — Screen recording +- **hyprpicker** — Color picker +- **wl-clipboard** — Clipboard management +- **wlr-randr** — Display management +- **NetworkManager** — Network management +- **BlueZ** — Bluetooth +- **pavucontrol** — Audio mixer +- **gvfs** — Virtual filesystem +- **GNOME Keyring** — Credential storage +- **xdg-desktop-portal-gnome** — Portal services + +--- + +## See Also + +- ](../system/index.md) — dankware overview +- [niri](niri/index.md) — Compositor documentation +- [[noctalia-shell|noctalia-shell]] — Desktop shell documentation +- [[applications|applications]] — Application reference diff --git a/omp-docs/tools/comfyui/index.md b/omp-docs/tools/comfyui/index.md new file mode 100644 index 0000000..14df027 --- /dev/null +++ b/omp-docs/tools/comfyui/index.md @@ -0,0 +1,87 @@ +# ComfyUI + +Node-based AI image generation engine running on `dankclaw`. Serves a web UI on port 8188. + +## Access + +Open `http://dankclaw:8188` in a browser. Accessible from any host on the 192.168.0.0/24 LAN. + +## Architecture + +| Property | Value | +|----------|-------| +| **Host** | dankclaw (192.168.0.143) | +| **Version** | v0.30.0 | +| **Python** | 3.14.4, venv at `~/ComfyUI/venv` | +| **PyTorch** | 2.13.0+cu130 (CPU backend) | +| **Backend** | CPU — ROCm unavailable on Strix Halo (GFX13) | +| **Model** | FLUX.2 [klein] 4B (7.3 GB, Apache 2.0) | +| **Service** | User-level systemd, `~/.config/systemd/user/comfyui.service` | +| **Models dir** | `~/models` via `extra_model_paths.yaml` | + +## Directory Layout + +``` +/home/dank/ +├── ComfyUI/ +│ ├── main.py # Entry point +│ ├── venv/ # Python virtual environment +│ ├── extra_model_paths.yaml # Links ~/models as model source +│ └── models/ # ComfyUI-native model subdirs (empty) +└── models/ + └── checkpoints/ + └── flux-2-klein-4b.safetensors +``` + +## Service Management + +```bash +# Check status +ssh dank@dankclaw 'systemctl --user status comfyui --no-pager' + +# Restart +ssh dank@dankclaw 'systemctl --user restart comfyui' + +# Stop +ssh dank@dankclaw 'systemctl --user stop comfyui' + +# View logs +ssh dank@dankclaw 'journalctl --user -u comfyui --no-pager -n 50' +``` + +## Add a New Model + +Place the `.safetensors` file in `~/models/checkpoints/`. ComfyUI detects it on restart. + +```bash +# Example: download a new model +ssh dank@dankclaw 'mkdir -p ~/models/checkpoints' +scp new-model.safetensors dank@dankclaw:~/models/checkpoints/ +ssh dank@dankclaw 'systemctl --user restart comfyui' +``` + +## Performance + +The AMD Ryzen AI MAX+ 395 has 16 CPU cores. ROCm does not support the Strix Halo (GFX13) APU in precompiled wheels. ComfyUI runs on CPU only. Expect generation times in the range of minutes per image. + +## ComfyUI-Manager + +Custom node manager installed at `~/ComfyUI/custom_nodes/ComfyUI-Manager`. Provides a UI to browse, install, and update custom nodes and models directly from the ComfyUI web interface. + +### Install a Custom Node + +1. Open the ComfyUI web UI +2. Click **Manager** in the sidebar +3. Search for the node and click **Install** +4. Restart ComfyUI when prompted + +### Update All Nodes + +```bash +ssh dank@dankclaw 'cd ~/ComfyUI && source venv/bin/activate && python custom_nodes/ComfyUI-Manager/cm-cli.sh update' && systemctl --user restart comfyui +``` + +## See Also + +- [Troubleshooting](troubleshooting.md) — Common errors and fixes +- [Dankclaw](../../system/dankclaw.md) — Host system overview diff --git a/omp-docs/tools/comfyui/troubleshooting.md b/omp-docs/tools/comfyui/troubleshooting.md new file mode 100644 index 0000000..6ed9730 --- /dev/null +++ b/omp-docs/tools/comfyui/troubleshooting.md @@ -0,0 +1,114 @@ +--- +type: reference +title: ComfyUI Troubleshooting +description: Common errors, diagnostics, and recovery steps for ComfyUI on dankclaw. +tags: + - image-generation + - comfyui + - troubleshooting + - dankclaw + - unverified +verified: 2026-08-28 +--- + +# ComfyUI Troubleshooting + +Procedures for diagnosing and fixing ComfyUI on dankclaw. + +## Service Will Not Start + +Check the journal logs first. + +```bash +ssh dank@dankclaw 'journalctl --user -u comfyui --no-pager -n 100' +``` + +### "RuntimeError: No HIP GPUs are available" + +Cause: The container's ROCm PyTorch cannot see the Strix Halo (gfx1151) GPU. This can happen when `/dev/kfd` and `/dev/dri` are not properly passthrough, or when the ROCm PyTorch build doesn't match the GPU architecture. + +Fix: Verify GPU passthrough is configured in `compose.yaml` (should include `/dev/kfd` and `/dev/dri`). The container image is `comfyui-rocm:gfx1151` which should contain the correct ROCm kernels. + +Check that the container image uses the AMD gfx1151 base: + +```bash +ssh dank@dankclaw 'podman inspect comfyui --format "{{.Config.Image}}"' +``` + +If the GPU still doesn't work, ensure the host user is in the `render` group: + +```bash +ssh dank@dankclaw 'id dank' +``` + +### "HIP error: invalid device function" + +Cause: The ROCm PyTorch kernels don't match the GPU architecture. The ComfyUI container uses the AMD gfx1151 base image (`comfyui-rocm:gfx1151`), but if PyTorch was reinstalled without the ROCm build, this error occurs. + +Fix: Reinstall the gfx1151 ROCm PyTorch. The container image already ships the correct version (torch 2.9.1+rocm). If the venv was rebuilt outside the container, reinstall: + +```bash +ssh dank@dankclaw 'cd ~/ComfyUI && source venv/bin/activate && \ + pip uninstall torch torchvision torchaudio pytorch-triton-rocm -y && \ + pip install torch torchvision torchaudio' +``` + +### Port 8188 Already in Use + +```bash +ssh dank@dankclaw 'ss -tlnp | grep 8188' +``` + +Kill the conflicting process or change the port in the service file. + +## Model Not Loading + +Check that the model file exists in the correct path. + +```bash +ssh dank@dankclaw 'ls -lh ~/models/checkpoints/*.safetensors' +``` + +Verify `extra_model_paths.yaml` points to the correct base path. + +```bash +ssh dank@dankclaw 'cat ~/ComfyUI/extra_model_paths.yaml' +``` + +Restart ComfyUI after adding or removing models. + +```bash +ssh dank@dankclaw 'systemctl --user restart comfyui' +``` + +## Cannot Reach the Web UI + +Test connectivity from dankware. + +```bash +curl -s -o /dev/null -w "%{http_code}" http://dankclaw:8188 +``` + +Expected response: `200`. + +If the response is empty or times out, verify the service is running. + +```bash +ssh dank@dankclaw 'systemctl --user status comfyui --no-pager' +ssh dank@dankclaw 'ss -tlnp | grep 8188' +``` + +## Out of Memory + +ComfyUI loads the full model into RAM. FLUX.2 klein 4B requires approximately 13 GB. The system has 119 GB total. Close other memory-intensive applications if OOM occurs. + +Check memory usage. + +```bash +ssh dank@dankclaw 'free -h' +ssh dank@dankclaw 'systemctl --user show comfyui --property=MemoryCurrent' +``` + +## See Also + +- [comfyui](index.md) — Main documentation diff --git a/omp-docs/tools/ghostty/configuration.md b/omp-docs/tools/ghostty/configuration.md new file mode 100644 index 0000000..48f5887 --- /dev/null +++ b/omp-docs/tools/ghostty/configuration.md @@ -0,0 +1,492 @@ +--- +type: reference +title: Ghostty Configuration Options — Complete Reference +description: Every configuration option for Ghostty, organized by category with types, defaults, and usage examples. +tags: + - terminal + - ghostty + - configuration + - reference +verified: 2026-08-28 +--- + +# Ghostty Configuration Reference + +Complete option catalog for [Ghostty](https://ghostty.org). See [Overview](index.md) for setup and quick-start. + +--- + +## Font Configuration + +### `font-family` + +**Type**: String (repeatable) + +Primary font family with fallback support. + +```ini +font-family = "JetBrains Mono" +font-family = "Noto Sans Mono" # fallback +``` + +Styles (bold, italic, bold-italic) are automatically found. Use `ghostty +list-fonts` to see available fonts. + +### `font-style`, `font-style-bold`, `font-style-italic`, `font-style-bold-italic` + +**Type**: String or `false` + +A named font style from the font's own style string, for example "Heavy" or "Semibold". Set to `false` to completely disable a style. + +### `font-synthetic-style` + +**Type**: String (comma-separated) + +Control whether Ghostty synthesizes missing styles. Values: `true`, `false`, `bold,italic,bold-italic`, `no-bold,no-italic`. + +### `font-feature` + +**Type**: String (repeatable, comma-separated) + +OpenType font features. Enable: `feat`, `+feat`, `feat on`, `feat=1`. Disable: `-feat`, `feat off`, `feat=0`. + +```ini +font-feature = -calt # disable programming ligatures +font-feature = -liga # disable standard ligatures +``` + +### `font-size` + +**Type**: Number (can be non-integer, in points) + +```ini +font-size = 12 +font-size = 13.5 # 27px on a 2x DPI display +``` + +### `font-variation` + +**Type**: String in `id=value` format (repeatable) + +Variable font axis values (4-character IDs). + +```ini +font-variation = wght=700 +font-variation = wdth=100 +``` + +### `font-codepoint-map` + +**Type**: String (repeatable) + +Force Unicode codepoints to map to a specific font. + +```ini +font-codepoint-map = U+2500-U+257F=JetBrains Mono +``` + +### `clipboard-codepoint-map` + +**Type**: String (repeatable) + +Map codepoints to replacement values when copying to clipboard. + +```ini +clipboard-codepoint-map = U+2500=U+002D # box drawing → hyphen +clipboard-codepoint-map = U+03A3=SUM # Greek sigma → "SUM" +``` + +### `grapheme-width-method` + +**Type**: String + +Width calculation method: `unicode` (default, correct but can cause cursor-desync) or `legacy` (wcswidth, maximizes compatibility). + +--- + +## Alpha Blending & Rendering + +### `alpha-blending` + +**Type**: String + +Color space for alpha blending (available since 1.1.0): `native` (OS-native, macOS default), `linear` (eliminates darkening artifacts), `linear-corrected` (Linux default). + +--- + +## Cell Adjustments + +All `adjust-*` options accept integers (1, -1) or percentages (20%, -15%). + +| Option | Description | +|--------|-------------| +| `adjust-cell-width` | Cell width adjustment | +| `adjust-cell-height` | Cell height (also centers font vertically, adjusts Powerline glyphs) | +| `adjust-font-baseline` | Baseline position | +| `adjust-underline-position` | Underline position | +| `adjust-underline-thickness` | Underline thickness | +| `adjust-strikethrough-position` | Strikethrough position | +| `adjust-strikethrough-thickness` | Strikethrough thickness | +| `adjust-overline-position` | Overline position | +| `adjust-overline-thickness` | Overline thickness | +| `adjust-cursor-thickness` | Bar/rect cursor thickness | +| `adjust-cursor-height` | Cursor height | +| `adjust-box-thickness` | Box drawing character thickness | +| `adjust-icon-height` | Nerd font icon height (available since 1.2.0) | + +**Warning**: Invalid values, for example -100%, can make the terminal unusable. + +--- + +## Theme & Colors + +### `theme` + +**Type**: String + +Theme name, absolute path, or light/dark pair: `light:Rose Pine Dawn,dark:Rose Pine`. + +### `background` / `foreground` + +**Type**: Color (`#RRGGBB`, `RRGGBB`, or named X11 color) + +### `palette` + +**Type**: `N=COLOR` (repeatable, N = 0–255) + +```ini +palette = 0=#1d1f21 +palette = 0x00=#1d1f21 +palette-generate = true +``` + +Only set 0-15 for most themes; 16-255 auto-generated if `palette-generate` is enabled. + +### `bold-color` + +**Type**: Color or `bright` (available since 1.2.0) + +Replaces deprecated `bold-is-bright`. + +### `minimum-contrast` + +**Type**: Number (1-21) + +Minimum contrast ratio (WCAG 2.0). Value of 3+ = avoid hard-to-read text. + +--- + +## Appearance + +### `background-image` + +**Type**: Path (PNG or JPEG, available since 1.2.0) + +Per-terminal background image. **Warning**: Currently duplicated in VRAM per-terminal. + +### `background-opacity` + +**Type**: Number (0-1) + +Window transparency. On macOS, disabled in native fullscreen. + +### `background-blur` + +**Type**: Number, `true`, `false`, or macOS special values + +Blur background when opacity < 1. macOS special: `macos-glass-regular`, `macos-glass-clear` (macOS 26.0+). + +--- + +## Selection + +### `copy-on-select` + +**Type**: Boolean or `clipboard` + +Automatically copy selected text. `clipboard` copies to both selection and system clipboard. + +### `selection-clear-on-typing` + +**Type**: Boolean (available since 1.2.0) + +Clear selection when typing. Default: `true`. + +--- + +## Cursor + +### `cursor-style` + +**Type**: String + +`block`, `bar`, `underline`, `block_hollow`. Programs can override via DECSCUSR. + +### `cursor-click-to-move` + +**Type**: Boolean + +Click to move cursor at prompts (requires shell integration). Default: `true`. + +--- + +## Mouse + +### `mouse-hide-while-typing` + +**Type**: Boolean + +Hide mouse when typing. + +### `mouse-reporting` + +**Type**: Boolean + +Allow terminal applications to receive mouse events. Default: `true`. Toggle with `toggle_mouse_reporting` keybind. + +--- + +## Scrolling + +### `scroll-to-bottom` + +**Type**: String (comma-separated) + +When to auto-scroll: `keystroke` (default), `output`. + +### `scrollback-limit` + +**Type**: Integer (bytes) + +Scrollback buffer size. Default: `10000000` (10 MB). + +--- + +## Split Panes + +### `unfocused-split-opacity` + +**Type**: Number (0.15-1) + +Opacity of unfocused split. Default: `0.7`. Minimum: `0.15`. + +### `split-divider-color` + +**Type**: Color (available since 1.1.0) + +Color of split dividers. + +--- + +## Shell Integration + +### `shell-integration` + +**Type**: String + +`none`, `detect` (default), `bash`, `elvish`, `fish`, `nushell`, `zsh`. `detect` auto-detects by filename. + +### `shell-integration-features` + +**Type**: String (comma-separated) + +Features: `cursor`, `sudo`, `title`, `ssh-env`, `ssh-terminfo`, `path`. Negate with `no-`. + +--- + +## Environment & Command + +### `command` + +**Type**: String + +Shell/command to run. Uses `/bin/sh -c` for argument expansion unless prefixed with `direct:` or `shell:`. + +### `env` + +**Type**: `KEY=VALUE` (repeatable, available since 1.2.0) + +Extra environment variables. Set `env =` to reset all. + +--- + +## Window Settings + +### `maximize` + +**Type**: Boolean (available since 1.1.0) + +Start maximized. Default: `false`. + +### `fullscreen` + +**Type**: String + +`false`, `true` (native), `non-native`, `non-native-visible-menu`, `non-native-padded-notch` (macOS only). + +### `window-decoration` + +**Type**: String or Boolean (available since 1.1.0) + +`none`, `auto` (default), `client`, `server`. Booleans: `true` = `auto`, `false` = `none`. + +### `window-padding-x` / `window-padding-y` + +**Type**: Number or `X,Y` + +Padding in points. Default: `2`. + +--- + +## Clipboard + +### `clipboard-read` / `clipboard-write` + +**Type**: String + +`ask`, `allow`, `deny`. Defaults: `ask` / `allow`. + +### `clipboard-paste-protection` + +**Type**: Boolean + +Require confirmation before pasting potentially unsafe text. Default: `true`. + +--- + +## Notifications & Bell + +### `bell-features` + +**Type**: String (comma-separated, available since 1.2.0) + +Features: `system`, `audio`, `attention` (default), `title` (default), `border`. Negate with `no-`. + +### `desktop-notifications` + +**Type**: Boolean + +Allow apps to show desktop notifications via escape sequences. Default: `true`. + +--- + +## Custom Shaders + +### `custom-shader` + +**Type**: Path (repeatable) + +GLSL shader file path. Compatible with Shadertoy. Receives uniforms: `iChannel0` (screen texture), `iResolution`, `iTime`, `iCursorColor`, `iPalette[256]`, and more. + +### `custom-shader-animation` + +**Type**: Boolean or `always` + +Run animation loop even when unfocused: `always`. + +--- + +## Keybindings + +### Format + +```ini +keybind = trigger=action +keybind = chain=action # chain with previous keybind +``` + +**Modifiers**: `shift`, `ctrl`/`control`, `alt`/`opt`/`option`, `super`/`cmd`/`command` + +**Prefixes**: `all:`, `global:`, `unconsumed:`, `performable:`, `physical:` + +### Key Tables (available since 1.3.0) + +```ini +keybind = foo/ctrl+a=new_window +keybind = foo/ # define and clear table +``` + +### Key Remap + +```ini +key-remap = ctrl=super +key-remap = left_control=right_alt +``` + +--- + +## VT/Compatibility + +### `term` + +**Type**: String + +TERM environment variable. Default: `xterm-ghostty`. + +### `async-backend` + +**Type**: String (available since 1.2.0, Linux only) + +`auto` (default), `epoll`, `io_uring`. macOS always uses `kqueue`. + +--- + +## Miscellaneous + +### `confirm-close-surface` + +**Type**: Boolean or `always` + +Confirm before closing surface. Default: `true`. + +### `focus-follows-mouse` + +**Type**: Boolean + +Auto-focus split under mouse. Default: `false`. + +### `right-click-action` + +**Type**: String + +`context-menu` (default), `paste`, `copy`, `copy-or-paste`, `ignore`. + +--- + +## Appendix: Default Keybindings + +| Keybind | Action | +|---------|--------| +| `ctrl+shift+,` | `reload_config` | +| `ctrl+,` | `open_config` | +| `copy` | `copy_to_clipboard:mixed` | +| `paste` | `paste_from_clipboard` | +| `ctrl+shift+c` | `copy_to_clipboard:mixed` | +| `ctrl+shift+v` | `paste_from_clipboard` | +| `ctrl+=` / `ctrl++` | `increase_font_size:1` | +| `ctrl+-` | `decrease_font_size:1` | +| `ctrl+0` | `reset_font_size` | +| `shift+PageUp` | `scroll_page_up` | +| `shift+PageDown` | `scroll_page_down` | +| `shift+Home` | `scroll_to_top` | +| `shift+End` | `scroll_to_bottom` | +| `ctrl+shift+Tab` | `previous_tab` | +| `ctrl+Tab` | `next_tab` | +| `ctrl+shift+n` | `new_window` | +| `ctrl+shift+w` | `close_tab:this` | +| `ctrl+shift+q` | `quit` | +| `ctrl+shift+t` | `new_tab` | +| `ctrl+shift+o` | `new_split:right` | +| `ctrl+shift+e` | `new_split:down` | +| `ctrl+shift+f` | `start_search` | +| `Escape` | `end_search` | +| `ctrl+shift+a` | `select_all` | +| `alt+1`-`alt+9` | `goto_tab:1`-`goto_tab:9` | +| `ctrl+Enter` | `toggle_fullscreen` | +| `ctrl+shift+P` | `toggle_command_palette` | + +--- + +## Cross-References + +- See [Overview](index.md) for CLI actions and quick-start. +- The [AGENTS.md Format](/core/agents-md-format.md) governs how agent behavior contracts reference this configuration. diff --git a/omp-docs/tools/ghostty/index.md b/omp-docs/tools/ghostty/index.md new file mode 100644 index 0000000..435824b --- /dev/null +++ b/omp-docs/tools/ghostty/index.md @@ -0,0 +1,124 @@ +# Ghostty Terminal — Overview + +[Ghostty](https://ghostty.org) is a cross-platform, GPU-accelerated terminal emulator with an INI-style configuration system, Shadertoy-compatible custom shaders, and a rich CLI for introspection. + +See [Configuration Reference](configuration.md) for the complete option catalog. + +--- + +## CLI Actions + +| Command | Description | +|---------|-------------| +| `+version` / `--version` | Display Ghostty version | +| `+list-fonts` | List all available fonts | +| `+list-keybinds` | List all current/default keybinds | +| `+list-themes` | List all available themes | +| `+list-colors` | List all named RGB colors | +| `+list-actions` | List all available keybind actions | +| `+ssh-cache` | Manage SSH terminfo cache | +| `+edit-config` | Open config file in $EDITOR/$VISUAL | +| `+show-config` | Show current configuration | +| `+show-config --default --docs` | Show all options with docs | +| `+validate-config` | Validate a config file | +| `+crash-report` | List existing crash reports | +| `+new-window` | Open new window in running instance | + +### Useful Flag Combinations + +```bash +# Show all config options with their docs as comments +ghostty +show-config --default --docs + +# List fonts with bold styles only +ghostty +list-fonts --bold + +# Validate your config without starting Ghostty +ghostty +validate-config +``` + +--- + +## Configuration File Basics + +Configuration uses INI-style syntax: + +```ini +option = value +option = "quoted value with spaces" +``` + +### Key Points + +- **Repeatable options**: `font-family`, `font-feature`, `palette`, `env`, `config-file`, `command-palette-entry`, `custom-shader` can all be repeated. +- **Empty string resets**: Set `option = ""` to clear previously set values. +- **Config includes**: Use `config-file = "path"` to include additional config files. +- **Optional includes**: Prepend `?` to suppress errors if file does not exist, for example `config-file = "?optional.conf"`. +- **CLI overrides**: CLI arguments automatically clear config file values for the same option. + +### Special Prefixes for Commands + +- `direct:` — Bypass shell expansion (no glob, tilde, or argument parsing) +- `shell:` — Force shell wrapping + +--- + +## Quick Configuration Examples + +```ini +# Font setup with fallback +font-family = "JetBrains Mono" +font-family = "Noto Sans Mono" # fallback for symbols +font-size = 12 + +# Disable programming ligatures +font-feature = -calt,-liga + +# Cursor +cursor-style = block +cursor-style-blink = false + +# Window padding +window-padding-x = 2 +window-padding-y = 2 + +# Palette +palette-generate = true +``` + +--- + +## Custom Shaders + +Ghostty supports Shadertoy-compatible GLSL shaders: + +```ini +custom-shader = ~/.config/ghostty/shaders/vignette.glsl +custom-shader-animation = true +``` + +Shaders receive uniforms for the terminal screen texture (`iChannel0`), cursor position, palette colors, and focus state. + +--- + +## Default Keybindings + +| Keybind | Action | +|---------|--------| +| `ctrl+shift+,` | `reload_config` | +| `ctrl+` / `ctrl+=` | `increase_font_size:1` | +| `ctrl+-` | `decrease_font_size:1` | +| `ctrl+0` | `reset_font_size` | +| `ctrl+shift+f` | `start_search` | +| `ctrl+shift+a` | `select_all` | +| `ctrl+Enter` | `toggle_fullscreen` | +| `ctrl+shift+P` | `toggle_command_palette` | + +See [Configuration Reference](configuration.md#appendix-default-keybindings) for the full table. + +--- + +## Cross-References + +- See [Configuration Reference](configuration.md) for every option, organized by category. +- The [AGENTS.md Format](../../core/agents-md-format.md) governs how agent behavior contracts reference this configuration. diff --git a/omp-docs/tools/gitea/architecture.md b/omp-docs/tools/gitea/architecture.md new file mode 100644 index 0000000..e78b1d0 --- /dev/null +++ b/omp-docs/tools/gitea/architecture.md @@ -0,0 +1,88 @@ +--- +type: reference +title: Gitea Architecture +description: Gitea container architecture, network topology, and Caddy reverse proxy configuration on dankclaw. +tags: + - gitea + - architecture + - unverified +verified: 2026-08-28 +--- + +# Gitea Architecture + +Three quadlet-managed containers on a shared private Podman network (rootless, user `dank`). Gitea connects to PostgreSQL via network DNS. Caddy proxies HTTP/S to Gitea. + +## Network Topology + +``` +Client (HTTPS) + ↓ +caddy :80/:443 (auto-TLS via Let's Encrypt DNS-01/Porkbun) + ↓ reverse_proxy 192.168.0.143:3000 (published quadlet port) +gitea-server :3000 (web UI, API) + ↓ PostgreSQL protocol +gitea-postgres :5432 (internal only) +``` + +## Network + +The containers share the quadlet network `systemd-gitea` (file `gitea.network`, DNS enabled by default). Container names resolve via network DNS. + +The automatic rootless `podman` default network has `dns_enabled: false`. Container names do not resolve there. Keep the Gitea stack on `systemd-gitea`. + +## Container and Unit Names + +| Container | Unit | Depends on | +|---|---|---| +| `gitea-postgres` | `gitea-postgres.service` | `gitea-network.service` | +| `gitea-server` | `gitea-server.service` | `gitea-postgres.service` | + +Podman 5.x names quadlet units after the file (`gitea-server.service`), with no `container-` prefix. + +## Caddy Configuration + +Caddy is a separate quadlet-managed service (`caddy.container`) on the shared `dankclaw_default` network. The live Caddyfile at `/home/dank/Containers/caddy/Caddyfile` proxies Gitea via the published quadlet port: + +``` +gitea.franksdank.cloud { + reverse_proxy 192.168.0.143:3000 +} +``` + +- Caddy issues Let's Encrypt certs via DNS-01 (Porkbun module) — no inbound HTTP port needed. +- Pi-hole quadlet resolves `gitea.franksdank.cloud` to `192.168.0.143` via `addn-hosts`. +- Serves HTTP on port 80 and HTTPS on port 443, both bound to `0.0.0.0`. + +## Gitea Configuration + +Quadlet file: `~/.config/containers/systemd/gitea-server.container` (repo copy: `serverAppConfigs/dankclaw/gitea/quadlet/gitea-server.container`) + +Key environment variables: +- `DATABASE_TYPE=postgres` +- `DATABASE_HOST=gitea-postgres` (network DNS) +- `DATABASE_NAME=gitea` +- `DATABASE_USER=gitea` +- `DATABASE_PASSWD` from `/opt/gitea/.env` (mode 0600) +- `USER_UID=1000`, `USER_GID=1000` + +Gitea writes `/data/gitea/conf/app.ini` on first start (host: `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini`). The `[database] HOST` and `PASSWD` lines in app.ini override the env vars. When you rename the database container, edit the `HOST` line in app.ini as well. + +## Ports + +| Service | Host Binding | Container Port | Access | +|---|---|---|---| +| Gitea HTTP | `0.0.0.0:3000` | 3000 | Web UI, API | +| Gitea SSH | `0.0.0.0:2222` | 22 | Git clone/push via SSH | +| PostgreSQL | `5432` (internal) | 5432 | Container-to-container only | + +Note: the full-stack repo compose (`dankclaw/compose.yaml`) maps Gitea HTTP to host port 3001. The live stack uses 3000. Align before the full-stack deploy. + + +`gitea.franksdank.cloud` resolves to `192.168.0.143` via the Pi-hole quadlet's `addn-hosts`. Caddy obtains Let's Encrypt certs via DNS-01 (Porkbun module), which requires no inbound port reachability. LAN clients reach Gitea via `http://dankclaw:3000` (published quadlet port). + +## See Also + +- ](index.md) — index with management commands +- [[management|management]] — operations, boot persistence, incident +- [[data-persistence|data-persistence]] — volumes and backups diff --git a/omp-docs/tools/gitea/data-persistence.md b/omp-docs/tools/gitea/data-persistence.md new file mode 100644 index 0000000..ec36c83 --- /dev/null +++ b/omp-docs/tools/gitea/data-persistence.md @@ -0,0 +1,69 @@ +--- +type: reference +title: Gitea Data Persistence +description: Gitea data persistence, volume mounts, ownership, and backup strategy on dankclaw. +tags: + - gitea + - data + - unverified +verified: 2026-08-28 +--- + +# Gitea Data Persistence + +All data lives on host bind mounts under `/opt/gitea/data/`. Containers are ephemeral. Quadlet stops remove the container (`podman run --rm --replace`). The next start recreates it. Data survives. + +## Volume Layout + +| Host Path | Container Mount | Contents | +|---|---|---| +| `/opt/gitea/data/gitea-gitea/` | `/data` | Git repositories, avatars, attachments, LFS objects, `app.ini` | +| `/opt/gitea/data/gitea-postgres/` | `/var/lib/postgresql/data` | PostgreSQL WAL, tables, indexes | + +## Ownership + +The bind-mount directories are owned by host user `dank` (UID 1000). Files that the containers create are owned by host UID/GID **100999** — the rootless ID mapping of container uid/gid 1000 (dank subuid range 100000-165535). User `dank` cannot write those files directly from the host. + +Edit container-owned files inside the container: + +``` +podman exec --user 1000 gitea-server sed -i 's/old/new/' /data/gitea/conf/app.ini +``` + +## Backup Strategy + +### Full backup (recommended) + +Tar the entire data directory. This captures Gitea repos and PostgreSQL data in one archive. + +``` +tar czf gitea-backup-$(date +%F).tar.gz -C /opt/gitea data/ +``` + +### PostgreSQL-only backup + +Use `pg_dump` for a portable SQL dump. Useful for restoring to a different PostgreSQL version. + +``` +podman exec -e PGPASSWORD="$GITEA_DB_PASSWORD" gitea-postgres pg_dump -U gitea gitea > gitea-db-$(date +%F).sql +``` + +Set `PGPASSWORD` from `/opt/gitea/.env` (mode 0600). + +### Restore procedure + +1. Stop the stack: `systemctl --user stop gitea-server gitea-postgres` +2. Restore data: `tar xzf backup.tar.gz -C /opt/gitea/` +3. Start the stack: `systemctl --user start gitea-postgres gitea-server` + +## Data Growth + +- Git repositories grow with each commit and push. Monitor with `du -sh /opt/gitea/data/gitea-gitea/git/repositories/`. +- PostgreSQL WAL files accumulate. VACUUM via `podman exec gitea-postgres psql -U gitea -c "VACUUM;"`. +- Gitea's log files grow with usage. + +## See Also + +- ](index.md) — index with management commands +- [[management|management]] — operations and boot persistence +- [[architecture|architecture]] — network and ports diff --git a/omp-docs/tools/gitea/index.md b/omp-docs/tools/gitea/index.md new file mode 100644 index 0000000..ef9c019 --- /dev/null +++ b/omp-docs/tools/gitea/index.md @@ -0,0 +1,65 @@ +# Gitea on dankclaw + +Private Git hosting on dankclaw. Three quadlet-managed containers in the rootless podman session of user `dank`: Gitea, PostgreSQL, Caddy. + +**Host:** dankclaw (71.227.227.172) +**Config:** `~/.config/containers/systemd/gitea-{postgres,server,caddy}.container` + `gitea.network` +**Local access:** `http://dankclaw:3000` +**Domain:** `https://gitea.franksdank.cloud` (DNS pending) + +## Architecture + +| Container | Unit | Port | Purpose | +|---|---|---|---| +| `gitea-server` | `gitea-server.service` | 3000 (HTTP), 2222 (SSH) | Git web UI, API, SSH daemon | +| `gitea-postgres` | `gitea-postgres.service` | 5432 (internal) | Database | +| `gitea-caddy` | `gitea-caddy.service` | 80, 443 | Reverse proxy, auto-TLS | + +The containers share the private network `systemd-gitea` (quadlet `gitea.network`, DNS enabled). The automatic `podman` default network has DNS disabled; do not run the stack on it. + +## Management + +All commands run as `dank` on dankclaw. + +| Action | Command | +|---|---| +| Start all | `systemctl --user start gitea-postgres gitea-server gitea-caddy` | +| Stop all | `systemctl --user stop gitea-caddy gitea-server gitea-postgres` | +| Restart Gitea only | `systemctl --user restart gitea-server` | +| Follow logs | `podman logs -f gitea-server` or `journalctl --user -u gitea-server -f` | +| Check status | `systemctl --user status gitea-postgres gitea-server gitea-caddy` | + +## Data Persistence + +All data lives on host bind mounts under `/opt/gitea/data/`. Containers are ephemeral. Stopping a quadlet unit removes its container; the next start recreates it. Volumes survive. + +| Volume Path | Container Mount | Contents | +|---|---|---| +| `/opt/gitea/data/gitea-gitea/` | `/data` | Git repositories, app.ini, attachments | +| `/opt/gitea/data/gitea-postgres/` | `/var/lib/postgresql/data` | PostgreSQL data files | +| `/opt/gitea/data/caddy/data/` | `/root/.local/share/caddy` | Caddy configuration, TLS certs | + +See [[data-persistence|data-persistence]] for backup and restore. + +## Boot Persistence + +User-level linger is enabled for `dank`. The units start at host boot without a login. Each unit carries `[Install] WantedBy=default.target`; the podman generator applies it. The legacy podman-compose stack had no units and did not survive reboots (incident 2026-08-16). + +See [[management|management]] for boot persistence details and troubleshooting. + +## Repo Copies + +The quadlet files, Caddyfile, and `.env.example` are tracked in the `serverAppConfigs` repo under `dankclaw/gitea/`. The live password lives only in `/opt/gitea/.env` on the host (mode 0600). + +## See Also + +- [[architecture|architecture]] — network topology and ports +- [[management|management]] — operations, upgrades, backups, incident log +- [[data-persistence|data-persistence]] — volumes and backup strategy +- [[containers|containers]] — quadlet reference + + * [Gitea Architecture](architecture.md) — Gitea container architecture, network topology, and Caddy reverse proxy configuration on dankclaw. + + * [Gitea Data Persistence](data-persistence.md) — Gitea data persistence, volume mounts, ownership, and backup strategy on dankclaw. + + * [Gitea Management](management.md) — Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw. diff --git a/omp-docs/tools/gitea/management.md b/omp-docs/tools/gitea/management.md new file mode 100644 index 0000000..9734f1c --- /dev/null +++ b/omp-docs/tools/gitea/management.md @@ -0,0 +1,106 @@ +--- +type: reference +title: Gitea Management +description: Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw. +tags: + - gitea + - management + - quadlet + - unverified +verified: 2026-08-28 +--- + +# Gitea Management + +All commands run as `dank` on dankclaw. The stack is quadlet-managed (since 2026-08-16). The legacy podman-compose file is retired to `/opt/gitea/.deprecated/`. + +## Daily Operations + +| Task | Command | +|---|---| +| Start all services | `systemctl --user start gitea-postgres gitea-server` | +| Stop all services | `systemctl --user stop gitea-server gitea-postgres` | +| Restart Gitea only | `systemctl --user restart gitea-server` | +| Follow container logs | `podman logs -f gitea-server` | +| Follow unit logs | `journalctl --user -u gitea-server -f` | +| Check status | `systemctl --user status gitea-postgres gitea-server` | +| Check health | `curl -s http://127.0.0.1:3000/api/v1/version` | + +Start the stack in order (postgres, server). The unit dependencies enforce the order when you start a single unit, but starting all three explicitly avoids surprises. + +## Boot Persistence + +| Setting | Value | Check | +|---|---|---| +| Quadlet units | `~/.config/containers/systemd/gitea-{postgres,server}.container`, `gitea.network` | `systemctl --user list-units 'gitea*'` | +| Boot enablement | `[Install] WantedBy=default.target` in each file | `systemctl --user is-enabled gitea-server` (reports `generated`) | +| User linger | enabled for `dank` | `loginctl show-user dank \| grep Linger` | + +At boot, systemd starts the user manager (linger), then `gitea-network.service`, then the containers in dependency order. No login session is required. + +After editing a quadlet file: run `systemctl --user daemon-reload`, then restart the affected units. + +## Config Files + +| File | Path | +|---|---| +| Quadlet units | `~/.config/containers/systemd/gitea-*.container`, `gitea.network` | +| Secrets | `/opt/gitea/.env` (mode 0600, `GITEA_DB_PASSWORD`) | +| Gitea app config | `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini` (container-owned, UID 100999) | + +Repo copies: `serverAppConfigs/dankclaw/gitea/` (quadlet files, `.env.example`). Copy edits to the target, then `daemon-reload` + restart. + +## Upgrades + +1. Pull latest images: `podman pull docker.io/gitea/gitea:latest` (repeat per image) +2. Restart the stack: `systemctl --user stop gitea-server gitea-postgres && systemctl --user start gitea-postgres gitea-server` +3. Verify startup: `podman logs -f gitea-server` + +Gitea handles database migrations automatically on startup. PostgreSQL version bumps require editing the image tag in `gitea-postgres.container`, then a dump/restore of the data (a fresh PostgreSQL does not read the old data directory format blindly). + +## Troubleshooting + +### Gitea cannot reach the database + +Check the `[database] HOST` line in `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini`. It must be `gitea-postgres:5432`. app.ini overrides the `DATABASE_HOST` env var. + +Then check name resolution from the container: + +``` +podman exec gitea-server getent hosts gitea-postgres +``` + +If it fails, the containers are not on the `systemd-gitea` network. Check `podman inspect gitea-server --format '{{.NetworkSettings.Networks}}'`. + +### Files in the data directory are not writable + +Container-created files are owned by host UID 100999 (rootless ID mapping of container uid 1000). Edit them inside the container: + +``` +podman exec --user 1000 gitea-server vi /data/gitea/conf/app.ini +``` + +### Caddy 502s + +The upstream `gitea-server:3000` is down or unresolvable. Start `gitea-server`, check its logs, and verify `/home/dank/Containers/caddy/Caddyfile` references `192.168.0.143:3000`. + +### Container names do not resolve + +The automatic rootless `podman` network has DNS disabled. Run the stack on `systemd-gitea` (see `gitea.network`). If the network state goes stale after a reboot, restart the stack; recreate the network only if restarts do not help. + +## Incident Log + +### 2026-08-16: down for ~1 hour after unattended reboot + +`unattended-upgrades` rebooted dankclaw at 15:01. The legacy podman-compose stack had no systemd units. Rootless podman does not auto-start containers at boot without units. Gitea stayed down until a manual start at 16:02. + +Fix: migrated the stack to quadlet units with `[Install] WantedBy=default.target` and enabled user-level linger. Also fixed two latent bugs found during the migration: the live Caddyfile upstream name (`server` → `192.168.0.143:3000`) and the stale `HOST = postgres:5432` line in app.ini (→ `gitea-postgres:5432`). + +Verify the fix on the next host reboot. + +## See Also + +- ](index.md) — index +- [[architecture|architecture]] — network topology +- [[data-persistence|data-persistence]] — backups +- [[containers|containers]] — quadlet reference diff --git a/omp-docs/tools/index.md b/omp-docs/tools/index.md new file mode 100644 index 0000000..66f3585 --- /dev/null +++ b/omp-docs/tools/index.md @@ -0,0 +1,39 @@ +# Tool Documentation + +Configuration guides and reference material for installed software. Each tool has its own directory with an `index.md` entry point. + +--- + +## Available Tools + +* [[cachyos|cachyos]] — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on dankware. +* [comfyui](comfyui/index.md) — Node-based AI image generation engine on dankclaw. FLUX.2 klein 4B, CPU backend, systemd managed. +* [[applications|applications]] — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming. +* ](ghostty/index.md) — GPU-accelerated terminal emulator with extensive configuration, keybindings, and shaders. +* ](gitea/index.md) — Private Git hosting on dankclaw. Quadlet-managed containers: Gitea, PostgreSQL, Caddy. +* ](llama-cpp/index.md) — Local LLM inference server supporting GGUF models with OpenAI-compatible API. +* [[linux-power-management|linux-power-management]] — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems. +* [[noctalia-shell|noctalia-shell]] — Desktop shell for Wayland built with Quickshell — launcher, wallpaper, session menu, lock screen, hotkey overlay, and media controls. +* [niri](niri/index.md) — Scrollable-tiling Wayland compositor — configuration, keybindings, and architecture for dankware. +* [npx Skills](npx-skills/index.md) — Distribution and installation tips for pi skill packages on npm, ecosystem overview, and skill specification. +* [ornith-llama-cpp-setup](ornith-llama-cpp-setup/index.md) — Setup and reference for running Ornith MoE models with llama.cpp server for local inference. +* [[tmux|tmux]] — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures. +* ](vercel-labs-skills/index.md) — Complete list of 68+ supported coding agents, their --agent flags, installation paths, and the SKILL.md specification. + +## Adding a New Tool + +1. Create a directory: `tools//` +2. Add `index.md` as the entry point (no frontmatter for directory listings) +3. Create concept files with frontmatter if content exceeds one file +4. Update this index +5. Log the change in `log.md` + +* [Default Applications](applications.md) — Default userspace applications on CachyOS with Niri — browsers, editor, terminal, file manager, audio, screenshots, gaming. + +* [CachyOS](cachyos.md) — Arch-based rolling release with performance-optimized kernels, repositories, and gaming stack. Running on dankware. + +* [Linux Power Management](linux-power-management.md) — Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems. + +* [Noctalia Shell](noctalia-shell.md) — Desktop shell for Wayland built with Quickshell — launcher, wallpaper, session menu, lock screen, hotkey overlay, and media controls. + +* [tmux](tmux.md) — Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures. diff --git a/omp-docs/tools/linux-power-management.md b/omp-docs/tools/linux-power-management.md new file mode 100644 index 0000000..8810172 --- /dev/null +++ b/omp-docs/tools/linux-power-management.md @@ -0,0 +1,301 @@ +--- +type: reference +title: Linux Power Management +description: Sleep/wake troubleshooting, NVIDIA GPU power management, and diagnostics for Linux systems. +tags: + - power-management + - sleep + - nvidia +timestamp: 2026-08-06 +--- + +Comprehensive guide to sleep/wake configuration and diagnostics on Linux systems. Covers systemd sleep, kernel states, NVIDIA GPU power management, and diagnostic tools. + +--- + +## Systemd Sleep Configuration + +### logind.conf (`/etc/systemd/logind.conf`) + +Controls login manager behavior around sleep: + +```ini +[Login] +HandlePowerKey=poweroff +HandleSleepKey=suspend +HandleHibernateKey=hibernate +HandleLidSwitch=suspend +HandleLidSwitchDocked=ignore +HoldoffTimeoutSec=5s +IdleAction=hibernate +IdleActionSec=30min +``` + +**Key setting**: `HoldoffTimeoutSec` — increase if sleep triggers are too aggressive. + +### sleep.conf (`/etc/systemd/sleep.conf`) + +Controls the actual sleep behavior: + +```ini +[Sleep] +AllowSuspend=yes +AllowHibernation=yes +AllowHybridSleep=yes +HibernateMode=platform+shutdown +HibernateDelaySec=1800 +``` + +**HibernateMode options**: +- `platform` — ACPI platform sleep (faster, firmware-dependent) +- `shutdown` — classic shutdown-to-disk (slower, more compatible) +- `shutdown+platform` — try platform first, fall back to shutdown + +### Suspend-Then-Hibernate Flow + +``` +Suspend (RAM) --timeout--> Hibernate (disk) + | + +-- wake event --> Resume +``` + +### Custom Sleep Hooks + +Create `/etc/systemd/system-sleep/` scripts for pre/post sleep actions: + +```bash +#!/bin/bash +# /etc/systemd/system-sleep/hook +case "$1" in + pre) echo "Suspending..." ;; + post) echo "Resumed!" ;; +esac +``` + +--- + +## Kernel Sleep States + +### ACPI Sleep States + +| State | Name | Power | Wake Time | Description | +|-------|------|-------|-----------|-------------| +| S0 | Working | Full | Instant | System is running | +| S1 | Sleep (halted) | ~10-20W | <1s | CPU halted, RAM refresh | +| S2 | Sleep | ~5-10W | ~1s | CPU cache flushed | +| **S3** | **Sleeping Standby** | **~1-5W** | **~1-2s** | **RAM retained, most power off** | +| S4 | Hibernate | 0W | ~10-30s | RAM written to disk | +| **S5** | **Soft Off** | **0W** | **~5-10s** | **Powered off but can wake** | + +### Modern ACPI Sleep States (s2idle) + +Modern laptops often **only support s2idle** (S0 idle): + +```bash +$ cat /sys/power/mem_sleep +[s2idle] deep +``` + +| Mode | Name | Power | Characteristics | +|------|------|-------|----------------| +| **s2idle** | "Suspend to Idle" | 3-8W | Shallow, firmware-managed, fast wake, higher drain | +| **deep** | S3 | 1-3W | Deeper sleep, slower wake, better battery | + +### Setting Default Sleep State + +Add to kernel command line (GRUB or systemd-boot): + +``` +mem_sleep_default=deep # Prefer S3 deep sleep +mem_sleep_default=s2idle # Force s2idle +``` + +**For GRUB:** Edit `/etc/default/grub`, add to `GRUB_CMDLINE_LINUX_DEFAULT`: +``` +GRUB_CMDLINE_LINUX_DEFAULT="... mem_sleep_default=deep" +``` + +--- + +## NVIDIA GPU Power Management + +### Enable NVIDIA Suspend Support + +```bash +sudo systemctl enable nvidia-suspend.service +sudo systemctl enable nvidia-suspend-then-hibernate.service +sudo systemctl enable nvidia-hibernate.service +``` + +### NVIDIA Module Parameters + +Edit `/etc/modprobe.d/nvidia.conf`: + +``` +options nvidia NVreg_PreserveVideoMemoryAllocations=1 +options nvidia NVreg_EnableS0ixPowerManagement=1 +``` + +### Check NVIDIA GPU State + +```bash +# Is the NVIDIA GPU active? +lspci -vnn | grep -A 12 -i "vga" + +# Force NVIDIA GPU to D3hot (fully off) before suspend +sudo tee /sys/bus/pci/devices/0000:01:00.0/power/control <<< auto +``` + +--- + +## Diagnostic Tools + +### journalctl + +```bash +# All sleep-related events in the last boot +journalctl -b -0 | grep -iE 'suspend|resume|sleep|wake|acpi' + +# Real-time monitoring during a suspend attempt +journalctl -f & +systemctl suspend +# Wait for failure, then Ctrl+C +``` + +### powertop + +```bash +sudo powertop # Interactive view +sudo powertop --calibrate # One-time setup +sudo powertop --auto-tune # Apply recommendations +sudo powertop --html=/tmp/report.html --csv=/tmp/report.csv +``` + +### tlp — Advanced Power Management + +```bash +sudo pacman -S tlp tlp-rdw # Arch +sudo apt install tlp # Debian/Ubuntu +sudo systemctl enable --now tlp +sudo tlp-stat +``` + +### dmesg + +```bash +dmesg | grep -iE 'suspend|resume|acpi|pm_' +dmesg -wH # Watch mode, human-readable +``` + +--- + +## Wake Source Management + +### Checking Wake Sources + +```bash +# What can wake the system? +cat /proc/acpi/wakeup | grep enabled + +# What woke the system last time? +journalctl -b -1 | grep -iE 'PM: wakeup|wakeup source|acpi: wakeup' +``` + +### Toggling Wake Sources + +```bash +# Toggle a device's wake capability +echo XHCI | sudo tee /proc/acpi/wakeup +echo RP01 | sudo tee /proc/acpi/wakeup +``` + +### Persistent Wake Source Configuration + +Create a systemd service: + +```ini +# /etc/systemd/system/config-wake-sources.service +[Unit] +Description=Configure ACPI wake sources +Before=sleep.target + +[Service] +Type=oneshot +ExecStart=/bin/bash -c 'echo XHCI > /proc/acpi/wakeup' +RemainAfterExit=yes + +[Install] +WantedBy=multi-user.target +``` + +--- + +## Common Kernel Parameters + +| Parameter | Description | +|-----------|-------------| +| `mem_sleep_default=deep` | Prefer S3 deep sleep | +| `pcie_aspm=force` | Force ASPM (aggressive power saving) | +| `pcie_aspm.policy=performance` | Disable ASPM (fixes some issues) | +| `acpi_osi=!` | Hide OS identity from ACPI | +| `usbcore.autosuspend=-1` | Disable USB autosuspend | + +--- + +## Testing Sleep Modes + +```bash +# Suspend to RAM +systemctl suspend + +# Hibernate to disk +systemctl hibernate + +# Suspend then hibernate +systemctl suspend-then-hibernate + +# Freeze (CPUs idle, RAM on) +systemctl freeze +``` + +### Automated Stress Test + +```bash +#!/bin/bash +for i in $(seq 1 10); do + echo "=== Cycle $i ===" + date + echo mem | sudo tee /sys/power/state 2>/dev/null || systemctl suspend + echo "Resume $i: SUCCESS" + sleep 5 +done +``` + +--- + +## Quick Reference: Action Items + +```bash +# 1. Enable NVIDIA suspend support +sudo systemctl enable nvidia-suspend.service +sudo systemctl enable nvidia-suspend-then-hibernate.service + +# 2. Add NVIDIA power management module parameter +echo 'options nvidia NVreg_PreserveVideoMemoryAllocations=1' | sudo tee /etc/modprobe.d/nvidia-preserve.conf + +# 3. Reboot +sudo reboot + +# 4. Test suspend +systemctl suspend + +# 5. After resume, check for errors +dmesg | tail -30 +journalctl -b -0 | grep -iE 'error|fail|nvidia' | tail -20 +``` + +--- + +## Cross-References + +- The [AGENTS.md Format](../core/agents-md-format.md) defines the system-level instruction contract that governs how agent sessions configure these systems. diff --git a/omp-docs/tools/llama-cpp/index.md b/omp-docs/tools/llama-cpp/index.md new file mode 100644 index 0000000..35e2d99 --- /dev/null +++ b/omp-docs/tools/llama-cpp/index.md @@ -0,0 +1,155 @@ +# llama.cpp Server — Overview + +[llama.cpp](https://github.com/ggml-org/llama.cpp) is a pure C/C++ LLM inference library. The `llama-server` binary is a lightweight, OpenAI-compatible HTTP server for serving GGUF models via REST API. + +See [Setup Guide](setup.md) for build instructions (CPU/CUDA/Metal/Vulkan), Docker, and systemd deployment. + +--- + +## Key Features + +- OpenAI API-compatible chat completions, completions, and embeddings +- Anthropic Messages API-compatible chat completions +- Parallel decoding with multi-user support and continuous batching +- Multimodal (vision/audio) support +- Speculative decoding with draft models +- Schema-constrained JSON output and function calling +- Built-in Web UI +- Prometheus metrics +- Router mode for multi-model deployment + +--- + +## GGUF Model Format + +**GGUF** (GGML Universal File) is the binary model file format used by llama.cpp. + +### Quantization Methods + +| Method | Bits/weight | 8B model size | Quality | +|--------|------------|---------------|---------| +| Q4_K_M | 4.9 | 4.58 GB | **Good (recommended default)** | +| Q5_K_M | 5.7 | 5.33 GB | High | +| Q6_K | 6.6 | 6.14 GB | Very High | +| Q8_0 | 8.5 | 7.95 GB | Near-lossless | +| F16 | 16.0 | 14.96 GB | Full precision | + +**Q4_K_M is the recommended default** — best balance of quality and size. + +--- + +## Quick Start + +```bash +# Serve a local model on default port 8080 +llama-server -m /path/to/model.gguf + +# From Hugging Face (auto-downloads) +llama-server -hf ggml-org/gemma-3-1b-it-GGUF +``` + +**Defaults**: Listens on `127.0.0.1:8080`. Single slot (one concurrent request). + +> **System note:** On this network the Pi inference hosts do not use the default port. Pi serves `frank-default-small` (dankserver) and `frank-default-large` (dankclaw), each on port `7770`. The local Ornith host runs on port `8080`. See [Pi Models Configuration](../../pi/models.md). + +--- + +## Health Check + +```bash +curl http://localhost:8080/health +# 200: {"status": "ok"} +# 503: {"error": {"code": 503, "message": "Loading model"}} +``` + +--- + +## API Endpoints + +### Chat Completions (OpenAI-compatible) + +```bash +curl http://localhost:8080/v1/chat/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer no-key" \ + -d '{ + "model": "gpt-3.5-turbo", + "messages": [ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Write a limerick about Python"} + ], + "max_tokens": 256, + "stream": true + }' +``` + +### Other Endpoints + +```bash +# Completions +curl http://localhost:8080/v1/completions + +# Embeddings +curl http://localhost:8080/v1/embeddings + +# Native completion +curl -X POST http://localhost:8080/completion -d '{"prompt": "Hello", "n_predict": 64}' + +# Anthropic-compatible +curl http://localhost:8080/v1/messages + +# Monitoring +curl http://localhost:8080/props +curl http://localhost:8080/slots +curl http://localhost:8080/metrics +``` + +--- + +## Python Client + +```python +import openai +client = openai.OpenAI( + base_url="http://localhost:8080/v1", + api_key="sk-no-key-required" +) +completion = client.chat.completions.create( + model="gpt-3.5-turbo", + messages=[{"role": "user", "content": "What is the meaning of life?"}], + max_tokens=256 +) +print(completion.choices[0].message.content) +``` + +--- + +## Docker + +```bash +docker run -p 8080:8080 -v /models:/models \ + ghcr.io/ggml-org/llama.cpp:server \ + -m /models/model.gguf --host 0.0.0.0 --port 8080 + +# CUDA variant +docker run -p 8080:8080 --gpus all \ + ghcr.io/ggml-org/llama.cpp:server-cuda \ + -m /models/model.gguf --n-gpu-layers 99 +``` + +--- + +## Environment Variables + +All CLI options can be set via `LLAMA_ARG_` prefix: + +```bash +LLAMA_ARG_MODEL=/models/model.gguf LLAMA_ARG_CTX_SIZE=8192 llama-server +``` + +--- + +## Cross-References + +- See [Setup Guide](setup.md) for build instructions, GPU offloading, and deployment. +- See [Ornith Setup](../ornith-llama-cpp-setup/index.md) for running Ornith models. diff --git a/omp-docs/tools/llama-cpp/setup.md b/omp-docs/tools/llama-cpp/setup.md new file mode 100644 index 0000000..8a9963b --- /dev/null +++ b/omp-docs/tools/llama-cpp/setup.md @@ -0,0 +1,266 @@ +--- +type: howto +title: llama.cpp — Build and Deployment Setup +description: Build guides for CPU, CUDA, Metal, Vulkan, and other GPU backends, plus Docker Compose and systemd service configuration. +tags: + - llm + - inference + - llama-cpp + - build + - deployment +verified: 2026-08-28 +--- + +# llama.cpp — Build and Deployment Setup + +See [Overview](index.md) for server usage and API reference. + +--- + +## Building llama.cpp + +### Prerequisites + +- Git +- CMake (3.12+) +- C++ compiler (GCC 9+, Clang 12+, MSVC 2019+) + +### CPU-only Build + +```bash +git clone https://github.com/ggml-org/llama.cpp +cd llama.cpp + +cmake -B build +cmake --build build --config Release -j 8 +``` + +The `llama-server` binary will be at `./build/bin/llama-server`. + +**Faster compilation:** +- Use Ninja: `cmake -B build -G Ninja` +- Install `ccache` for incremental builds + +**Debug build:** +```bash +cmake -B build -DCMAKE_BUILD_TYPE=Debug +cmake --build build +``` + +### CUDA Build (NVIDIA GPU) + +```bash +# Requires CUDA toolkit installed +cmake -B build -DGGML_CUDA=ON +cmake --build build --config Release -j 8 +``` + +**Non-native build (works on all CUDA GPUs):** +```bash +cmake -B build -DGGML_CUDA=ON -DGGML_NATIVE=OFF +cmake --build build --config Release +``` + +**Override compute capabilities:** +```bash +cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="86;89" +``` + +### Metal Build (Apple Silicon) + +Metal is enabled by default on macOS. No special flags needed: + +```bash +cmake -B build +cmake --build build --config Release +``` + +Disable GPU offloading at runtime with `--n-gpu-layers 0`. + +### Other GPU Backends + +| Backend | Flag | Platform | +|---------|------|----------| +| HIP/ROCm (AMD GPU) | `-DGGML_HIP=ON` | Linux | +| Vulkan | `-DGGML_VULKAN=ON` | All | +| SYCL (Intel GPU) | `-DGGML_SYCL=ON` | Linux | +| CANN (Ascend NPU) | `-DGGML_CANN=ON` | Linux | +| OpenVINO | `-DGGML_OPENVINO=ON` | Intel | +| ZenDNN (AMD CPU) | `-DGGML_ZENDNN=ON` | Linux | +| WebGPU | `-DGGML_WEBGPU=ON` | All (WASM) | + +### SSL/TLS Support + +```bash +# Requires OpenSSL dev libraries +cmake -B build -DLLAMA_OPENSSL=ON +cmake --build build --config Release -t llama-server +``` + +--- + +## Key Command-Line Options + +### Model Loading + +| Flag | Description | Default | +|------|-------------|---------| +| `-m, --model FNAME` | Path to GGUF model file | required | +| `-hf, --hf-repo USER/MODEL` | Download from Hugging Face | — | +| `-mmproj FILE` | Multimodal projector file | — | +| `-lora FNAME` | LoRA adapter (repeatable) | — | +| `-ngl, --gpu-layers N` | Layers to offload to GPU | auto | + +### Context & Performance + +| Flag | Description | Default | +|------|-------------|---------| +| `-c, --ctx-size N` | Prompt context size | 0 (from model) | +| `-t, --threads N` | CPU threads | -1 (all) | +| `-b, --batch-size N` | Max logical batch size | 2048 | +| `--flash-attn` | Flash Attention | auto | +| `--mlock` | Keep model in RAM (no swap) | false | +| `--mmap` | Memory-map model file | true | +| `--fit` | Auto-fit to GPU memory | on | + +### Server Configuration + +| Flag | Description | Default | +|------|-------------|---------| +| `--host HOST` | Bind address | 127.0.0.1 | +| `--port PORT` | Port number | 8080 | +| `-np, --parallel N` | Concurrent slots | -1 (auto) | +| `--api-key KEY` | API key (repeatable) | none | +| `--metrics` | Prometheus metrics | disabled | +| `--jinja` | Jinja template engine | enabled | + +### Sampling Parameters + +| Flag | Description | Default | +|------|-------------|---------| +| `-s, --seed N` | RNG seed | -1 (random) | +| `--temp, --temperature N` | Temperature | 0.80 | +| `--top-k N` | Top-k sampling | 40 | +| `--top-p N` | Top-p sampling | 0.95 | +| `--min-p N` | Min-p sampling | 0.05 | +| `--repeat-penalty N` | Repetition penalty | 1.1 | + +--- + +## GPU Offloading + +```bash +# Offload all layers to GPU +llama-server -m model.gguf --n-gpu-layers 99 + +# Auto-detect (default) +llama-server -m model.gguf --n-gpu-layers auto + +# Disable GPU (CPU-only) +llama-server -m model.gguf --n-gpu-layers 0 + +# Multi-GPU (layer mode) +llama-server -m model.gguf --device 0,1 --split-mode layer + +# Multi-GPU (row split) +llama-server -m model.gguf --device 0,1 --split-mode row +``` + +--- + +## Context Length + +```bash +# Use model's native context +llama-server -m model.gguf -c 0 + +# Set specific context +llama-server -m model.gguf -c 8192 + +# RoPE scaling to extend beyond trained size +llama-server -m model.gguf -c 65536 --rope-scale 2 + +# YaRN scaling +llama-server -m model.gguf -c 65536 --rope-scaling yarn --yarn-orig-ctx 8192 +``` + +**Important**: Larger context = more VRAM/RAM usage (KV cache grows linearly). Reduce with quantization: + +```bash +llama-server -m model.gguf -c 32768 \ + --cache-type-k q4_0 --cache-type-v q4_0 +``` + +--- + +## Speculative Decoding + +```bash +# Draft model based +llama-server -m main_model.gguf -md draft_model.gguf + +# N-gram based (no draft model needed) +llama-server -m model.gguf --spec-type ngram-mod --spec-ngram-mod-n-max 64 +``` + +--- + +## Docker Compose Example + +```yaml +services: + llamacpp-server: + image: ghcr.io/ggml-org/llama.cpp:server-cuda + ports: + - 8080:8080 + volumes: + - ./models:/models + environment: + LLAMA_ARG_MODEL: /models/my_model.gguf + LLAMA_ARG_CTX_SIZE: 8192 + LLAMA_ARG_N_PARALLEL: 2 + LLAMA_ARG_PORT: 8080 + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: 1 + capabilities: [gpu] +``` + +--- + +## Running as systemd Service + +```ini +# /etc/systemd/system/llama-server.service +[Unit] +Description=llama.cpp Server +After=network.target + +[Service] +Type=simple +User=dank +ExecStart=/home/dank/GitPackages/llama.cpp/build/bin/llama-server \ + -m /home/dank/models/my_model.gguf -c 131072 -ngl 12 \ + --host 0.0.0.0 --port 8080 +Restart=on-failure +WorkingDirectory=/home/dank/GitPackages/llama.cpp + +[Install] +WantedBy=multi-user.target +``` + +```bash +sudo systemctl daemon-reload +sudo systemctl enable llama-server +sudo systemctl start llama-server +``` + +--- + +## Cross-References + +- See [Overview](index.md) for API reference and usage examples. +- See [Ornith Setup](../ornith-llama-cpp-setup/index.md) for model-specific configuration. diff --git a/omp-docs/tools/niri/action-reference.md b/omp-docs/tools/niri/action-reference.md new file mode 100644 index 0000000..13b68aa --- /dev/null +++ b/omp-docs/tools/niri/action-reference.md @@ -0,0 +1,71 @@ +--- +type: reference +title: Niri Action Reference +description: Complete reference of all available niri actions — window operations, focus, movement, spawning, and system actions. +tags: + - niri + - actions + - reference +verified: 2026-08-28 +--- + +# Action Reference + +## Window/Column Actions + +- `close-window` — Close focused window +- `toggle-window-floating` — Toggle floating/tiling +- `maximize-column` — Maximize column with gaps +- `maximize-window-to-edges` — Maximize without gaps +- `expand-column-to-available-width` — Fill remaining space +- `center-column` — Center focused column +- `center-visible-columns` — Center all visible columns +- `switch-preset-column-width` — Cycle preset widths +- `switch-preset-column-width-back` — Cycle backwards +- `switch-preset-window-height` — Cycle preset heights +- `reset-window-height` — Reset height +- `toggle-column-tabbed-display` — Toggle vertical tabs mode +- `consume-or-expel-window-left/right` — Consume/expel window +- `consume-window-into-column` — Consume window into column +- `expel-window-from-column` — Expel window from column +- `set-column-width "-10%"` / `set-column-width "+10%"` — Fine width adjustment +- `set-window-height "-10%"` / `set-window-height "+10%"` — Fine height adjustment + +## Focus Actions + +- `focus-column-left/right` — Focus adjacent column +- `focus-window-up/down` — Focus window within column +- `focus-column-first/last` — Focus first/last column +- `focus-workspace N` — Focus workspace N +- `focus-workspace-down/up` — Focus next/previous workspace +- `focus-workspace-previous` — Focus previously active workspace +- `focus-monitor-left/right/up/down` — Focus adjacent monitor + +## Move Actions + +- `move-column-left/right` — Move column left/right +- `move-window-up/down` — Move window within column +- `move-column-to-first/last` — Move column to edge +- `move-column-to-workspace-down/up` — Move column to adjacent workspace +- `move-column-to-workspace N` — Move column to workspace N +- `move-column-to-monitor-left/right/up/down` — Move column to adjacent monitor + +## Other Actions + +- `spawn "program"` — Run program (no shell expansion) +- `spawn-sh "command"` — Run command through shell +- `spawn-at-startup "program"` — Run at startup +- `quit` — Quit compositor (with confirmation) +- `show-hotkey-overlay` — Show keybind cheat sheet +- `toggle-overview` — Toggle overview +- `screenshot` — Interactive screenshot +- `screenshot-screen` — Screenshot monitor +- `screenshot-window` — Screenshot window +- `power-off-monitors` — Turn off displays +- `toggle-keyboard-shortcuts-inhibit` — Toggle inhibitor +- `do-screen-transition` — Smooth screen transition (for theme switching) + +## Related + +* [Default Bindings](/tools/niri/default-bindings.md) — Default key bindings that invoke these actions +* [Tips](/tools/niri/tips.md) — Programmatic invocation and other tips diff --git a/omp-docs/tools/niri/default-bindings.md b/omp-docs/tools/niri/default-bindings.md new file mode 100644 index 0000000..7aee934 --- /dev/null +++ b/omp-docs/tools/niri/default-bindings.md @@ -0,0 +1,181 @@ +--- +type: reference +title: Niri Default Key Bindings +description: Complete table of all default key bindings organized by category — window management, navigation, workspaces, media keys, etc. +tags: + - niri + - keybindings + - reference + - unverified +--- + +# Default Key Bindings + +## Application Launching + +| Key | Action | +|-----|--------| +| `Mod+T` | Open terminal (alacritty) | +| `Mod+D` | Run application launcher (fuzzel) | +| `Super+Alt+L` | Lock screen (swaylock) | +| `Super+Alt+S` | Toggle screen reader (orca) | + +## Window Management + +| Key | Action | +|-----|--------| +| `Mod+Q` | Close window | +| `Mod+F` | Maximize column (with gaps) | +| `Mod+Shift+F` | Fullscreen window | +| `Mod+M` | Maximize window to edges (like double-click titlebar) | +| `Mod+Ctrl+F` | Expand column to fill remaining space | +| `Mod+V` | Toggle window floating | +| `Mod+Shift+V` | Switch focus between floating and tiling | +| `Mod+W` | Toggle column tabbed display mode | +| `Mod+BracketLeft` | Consume/expel window left | +| `Mod+BracketRight` | Consume/expel window right | +| `Mod+Comma` | Consume window into column | +| `Mod+Period` | Expel window from column | + +## Column Navigation + +| Key | Action | +|-----|--------| +| `Mod+Left` or `Mod+H` | Focus column left | +| `Mod+Right` or `Mod+L` | Focus column right | +| `Mod+Home` | Focus first column | +| `Mod+End` | Focus last column | +| `Mod+C` | Center focused column | +| `Mod+Ctrl+C` | Center all visible columns | + +## Column Movement + +| Key | Action | +|-----|--------| +| `Mod+Ctrl+Left` or `Mod+Ctrl+H` | Move column left | +| `Mod+Ctrl+Right` or `Mod+Ctrl+L` | Move column right | +| `Mod+Ctrl+Home` | Move column to first position | +| `Mod+Ctrl+End` | Move column to last position | + +## Column Sizing + +| Key | Action | +|-----|--------| +| `Mod+R` | Switch preset column width (1/3, 1/2, 2/3) | +| `Mod+Shift+R` | Switch preset width (reverse) | +| `Mod+Minus` | Decrease column width by 10% | +| `Mod+Equal` | Increase column width by 10% | + +## Window Navigation (within column) + +| Key | Action | +|-----|--------| +| `Mod+Up` or `Mod+K` | Focus window up | +| `Mod+Down` or `Mod+J` | Focus window down | + +## Window Height Sizing + +| Key | Action | +|-----|--------| +| `Mod+Ctrl+Shift+R` | Switch preset window height | +| `Mod+Ctrl+R` | Reset window height | +| `Mod+Shift+Minus` | Decrease window height by 10% | +| `Mod+Shift+Equal` | Increase window height by 10% | + +## Multi-Monitor Navigation + +| Key | Action | +|-----|--------| +| `Mod+Shift+Left` or `Mod+Shift+H` | Focus monitor left | +| `Mod+Shift+Right` or `Mod+Shift+L` | Focus monitor right | +| `Mod+Shift+Up` or `Mod+Shift+K` | Focus monitor up | +| `Mod+Shift+Down` or `Mod+Shift+J` | Focus monitor down | + +## Multi-Monitor Column Movement + +| Key | Action | +|-----|--------| +| `Mod+Shift+Ctrl+Left` | Move column to monitor left | +| `Mod+Shift+Ctrl+Right` | Move column to monitor right | +| `Mod+Shift+Ctrl+Up` | Move column to monitor up | +| `Mod+Shift+Ctrl+Down` | Move column to monitor down | + +## Workspace Navigation + +| Key | Action | +|-----|--------| +| `Mod+Page_Down` or `Mod+U` | Focus workspace down | +| `Mod+Page_Up` or `Mod+I` | Focus workspace up | +| `Mod+1` through `Mod+9` | Focus workspace 1-9 | +| `Mod+Shift+Page_Down` or `Mod+Shift+U` | Move workspace down | +| `Mod+Shift+Page_Up` or `Mod+Shift+I` | Move workspace up | +| `Mod+Tab` | Focus previous workspace (commented out by default) | + +## Workspace Column Movement + +| Key | Action | +|-----|--------| +| `Mod+Ctrl+Page_Down` or `Mod+Ctrl+U` | Move column to workspace down | +| `Mod+Ctrl+Page_Up` or `Mod+Ctrl+I` | Move column to workspace up | +| `Mod+Ctrl+1` through `Mod+Ctrl+9` | Move column to workspace 1-9 | + +## Mouse/Touchpad Scrolling + +| Key | Action | +|-----|--------| +| `Mod+WheelScrollDown` | Focus workspace down | +| `Mod+WheelScrollUp` | Focus workspace up | +| `Mod+WheelScrollRight` | Focus column right | +| `Mod+WheelScrollLeft` | Focus column left | +| `Mod+Ctrl+WheelScrollDown` | Move column to workspace down | +| `Mod+Ctrl+WheelScrollUp` | Move column to workspace up | +| `Mod+Ctrl+WheelScrollRight` | Move column right | +| `Mod+Ctrl+WheelScrollLeft` | Move column left | +| `Mod+Shift+WheelScrollDown` | Focus column right | +| `Mod+Shift+WheelScrollUp` | Focus column left | +| `Mod+Ctrl+Shift+WheelScrollDown` | Move column right | +| `Mod+Ctrl+Shift+WheelScrollUp` | Move column left | + +## Overview + +| Key | Action | +|-----|--------| +| `Mod+O` | Toggle overview (zoomed-out view of workspaces/windows) | + +## Screenshot + +| Key | Action | +|-----|--------| +| `Print` | Interactive screenshot UI | +| `Ctrl+Print` | Screenshot screen | +| `Alt+Print` | Screenshot window | + +## System + +| Key | Action | +|-----|--------| +| `Mod+Shift+E` | Quit niri (with confirmation) | +| `Ctrl+Alt+Delete` | Quit niri (with confirmation) | +| `Mod+Shift+P` | Power off monitors | +| `Mod+Escape` | Toggle keyboard shortcuts inhibitor | +| `Mod+Shift+/` | Show hotkey overlay | + +## Media Keys + +| Key | Action | +|-----|--------| +| `XF86AudioRaiseVolume` | Increase volume 10% | +| `XF86AudioLowerVolume` | Decrease volume 10% | +| `XF86AudioMute` | Toggle mute | +| `XF86AudioMicMute` | Toggle mic mute | +| `XF86AudioPlay` / `XF86AudioPause` | Play/pause | +| `XF86AudioStop` | Stop | +| `XF86AudioPrev` | Previous track | +| `XF86AudioNext` | Next track | +| `XF86MonBrightnessUp` | Increase brightness 10% | +| `XF86MonBrightnessDown` | Decrease brightness 10% | + +## Related + +* [Key Bindings Syntax](/tools/niri/key-bindings-syntax.md) — How to write custom bindings +* [Action Reference](/tools/niri/action-reference.md) — All available actions diff --git a/omp-docs/tools/niri/index.md b/omp-docs/tools/niri/index.md new file mode 100644 index 0000000..bb24054 --- /dev/null +++ b/omp-docs/tools/niri/index.md @@ -0,0 +1,95 @@ +# Niri Wayland Compositor + +Niri is a scrollable-tiling Wayland compositor. Windows are arranged in columns that scroll horizontally. It uses KDL-format configuration with an include-based modular structure. + +**Version:** 26.04 (8ed0da4) +**Config:** `~/.config/niri/config.kdl` + +--- + +## Configuration Structure + +``` +~/.config/niri/ +├── config.kdl # Main entry, includes all modules +└── cfg/ + ├── animation.kdl # Spring and curve animations + ├── autostart.kdl # Startup applications + ├── display.kdl # Output configuration + ├── input.kdl # Keyboard, touchpad, mouse + ├── keybinds.kdl # All key bindings + ├── layout.kdl # Gaps, column widths, struts + ├── rules.kdl # Window and layer rules + └── misc.kdl # Environment, cursor, debug +``` + +## Layout + +Column-based scrollable tiling. Columns are cycled with Mod+Left/Right (or Mod+H/L). Windows within columns stack vertically. + +| Setting | Value | +|---------|-------| +| **Gaps** | 16px | +| **Center focused column** | Never | +| **Background** | Transparent (for Noctalia wallpaper) | +| **Column presets** | 33%, 50%, 67% | + +## Input + +| Setting | Value | +|---------|-------| +| **Focus follows mouse** | Enabled | +| **Workspace back-and-forth** | Enabled | +| **Numlock** | Enabled on startup | +| **Touchpad tap** | Enabled | +| **Natural scroll** | Enabled | + +## Window Rules + +| Rule | Match | Effect | +|------|-------|--------| +| All windows | — | 20px corner radius, clipped | +| Steam (non-window) | `app-id="steam"`, exclude title `Steam` | Open floating | +| Steam notifications | `app-id="steam"`, title `notificationtoasts_*` | Floating, bottom-right | +| Noctalia wallpaper | namespace `noctalia-wallpaper*` | Place in backdrop | + +## Environment Variables + +| Variable | Value | Purpose | +|----------|-------|---------| +| `ELECTRON_OZONE_PLATFORM_HINT` | `auto` | Electron Wayland support | +| `QT_QPA_PLATFORM` | `wayland` | Qt Wayland | +| `QT_QPA_PLATFORMTHEME` | `gtk3` | Qt GTK theme | +| `QT_WAYLAND_DISABLE_WINDOWDECORATION` | `1` | Remove Qt CSD | +| `XDG_CURRENT_DESKTOP` | `niri` | Desktop identification | +| `XDG_SESSION_TYPE` | `wayland` | Session type | +| `render-node` | `/dev/dri/renderD129` | Intel Arc iGPU | + +## Animations + +| Animation | Type | Parameters | +|-----------|------|------------| +| Workspace switch | Spring | damping=1.0, stiffness=1000 | +| Window open | Duration | 200ms, ease-out-quad | +| Window close | Duration | 200ms, ease-out-cubic | +| Window movement | Spring | damping=1.0, stiffness=800 | +| Window resize | Spring | damping=1.0, stiffness=1000 | + +--- + +## Concept Files + +| File | Type | Description | +|------|------|-------------| +| [[action-reference|action-reference.md]] | reference | Complete reference of all available niri actions | +| [[default-bindings|default-bindings.md]] | reference | Default key bindings organized by category | +| [[key-bindings-syntax|key-bindings-syntax.md]] | reference | KDL configuration syntax for key bindings | +| [[tips|tips.md]] | howto | Practical tips for working with niri | + +--- + +## See Also + +- [[noctalia-shell|noctalia-shell]] — Desktop shell integration +- [[displays|displays]] — Three-monitor setup +- [[cachyos|cachyos]] — Operating system diff --git a/omp-docs/tools/niri/key-bindings-syntax.md b/omp-docs/tools/niri/key-bindings-syntax.md new file mode 100644 index 0000000..74527f5 --- /dev/null +++ b/omp-docs/tools/niri/key-bindings-syntax.md @@ -0,0 +1,60 @@ +--- +type: reference +title: Niri Key Bindings Syntax +description: Configuration syntax for niri key bindings — KDL format, modifiers, bind options, and finding key names with wev. +tags: + - niri + - keybindings + - kdl + - configuration +verified: 2026-08-28 +--- + +# Key Bindings Syntax + +Key bindings go in the `binds {}` section of the config file (`~/.config/niri/config.kdl`): + +```kdl +binds { + Mod+T { spawn "alacritty"; } + Mod+Left { focus-column-left; } +} +``` + +## Modifiers + +- `Ctrl` or `Control` +- `Shift` +- `Alt` +- `Super` or `Win` +- `ISO_Level3_Shift` or `Mod5` (AltGr) +- `ISO_Level5_Shift` (for lv5 options like `lv5:caps_switch`) +- `Mod` — Special: equals `Super` on TTY, equals `Alt` in nested window + +## Bind Options + +```kdl +binds { + Mod+T repeat=false { spawn "alacritty"; } // Do not repeat on hold + Mod+T cooldown-ms=500 { spawn "alacritty"; } // Rate-limit + Super+Alt+L allow-when-locked=true { spawn "swaylock"; } // Works when locked + Mod+Q hotkey-overlay-title="Close Window" { close-window; } // Custom title in overlay + Mod+Escape allow-inhibiting=false { ... } // Always works (even with inhibitors) +} +``` + +## Finding Key Names + +Use [`wev`](https://git.sr.ht/~sircmpwn/wev) to find XKB key names: + +```bash +wev +# Then press the key you want to bind — look at `sym: XXXX` in output +``` + +Shifted keys require Shift + the unshifted key (for example, `Mod+Shift+Comma` for `<` on US QWERTY). + +## Related + +* [Default Key Bindings](/tools/niri/default-bindings.md) — What niri ships with out of the box +* [Action Reference](/tools/niri/action-reference.md) — All available actions diff --git a/omp-docs/tools/niri/tips.md b/omp-docs/tools/niri/tips.md new file mode 100644 index 0000000..8d9a9db --- /dev/null +++ b/omp-docs/tools/niri/tips.md @@ -0,0 +1,41 @@ +--- +type: howto +title: Niri Tips and Gotchas +description: Practical tips for working with niri — Mod key behavior, shell expansion, config reload, vim keys, and programmatic invocation. +tags: + - niri + - tips + - gotchas +verified: 2026-08-28 +--- + +# Helpful Tips + +## 1. Mod key + +Use `Mod` instead of `Super` for configs that work both on TTY and in nested windows. + +## 2. No shell expansion in spawn + +`spawn` does not expand `$VAR` or `~`. Use `spawn-sh` or wrap in `sh -c`. + +## 3. Config reload + +niri supports live-reloading config without restart. + +## 4. Alternative navigation + +Vim-like keys (H/J/K/L) are bound by default alongside arrow keys. + +## 5. Programmatic invocation + +Every action can be invoked via `niri msg action `. + +## 6. Find XKB keys + +Use `wev` to discover key names. + +## Related + +* [Key Bindings Syntax](/tools/niri/key-bindings-syntax.md) — Configuration details +* [Action Reference](/tools/niri/action-reference.md) — All available actions diff --git a/omp-docs/tools/noctalia-shell.md b/omp-docs/tools/noctalia-shell.md new file mode 100644 index 0000000..0f64aa8 --- /dev/null +++ b/omp-docs/tools/noctalia-shell.md @@ -0,0 +1,128 @@ +--- +type: reference +title: Noctalia Shell +description: Desktop shell for Wayland built with Quickshell — launcher, wallpaper, session menu, lock screen, hotkey overlay, and media controls. +tags: + - noctalia + - quickshell + - wayland + - shell + - launcher +timestamp: 2026-08-06 +--- + +# Noctalia Shell + +Noctalia Shell is a sleek, minimal desktop shell for Wayland built with [Quickshell](https://github.com/outfoxxed/quickshell). It provides an app launcher, wallpaper manager, session menu, lock screen, hotkey overlay, media controls, and brightness/volume controls. + +**Version:** 4.7.7 +**Dependency:** noctalia-qs / qs 0.0.12 + +--- + +## Architecture + +Noctalia communicates through an IPC system accessed via the `qs` command: + +```bash +qs -c noctalia-shell ipc call [params] +``` + +## Components + +| Component | IPC Command | Description | +|-----------|-------------|-------------| +| **Shell** | `qs -c noctalia-shell` | Main shell process | +| **Launcher** | `ipc call launcher toggle` | Application launcher | +| **Lock Screen** | `ipc call lockScreen lock` | Screen locker | +| **Session Menu** | `ipc call sessionMenu toggle` | Power/logout menu | +| **Hotkey Overlay** | `ipc call overlay toggle` | Visual keybind reference | +| **Volume** | `ipc call volume increase/decrease/muteOutput` | Audio controls | +| **Media** | `ipc call media playPause/next/previous` | Media playback | +| **Brightness** | `ipc call brightness increase/decrease` | Display brightness | +| **Wallpaper** | Layer namespace `noctalia-wallpaper*` | Desktop wallpaper | + +--- + +## Niri Integration + +Noctalia is deeply integrated with the Niri compositor configuration: + +### Autostart + +**File:** `~/.config/niri/cfg/autostart.kdl` + +```kdl +spawn-sh-at-startup "qs -c noctalia-shell" +``` + +### Keybindings + +**File:** `~/.config/niri/cfg/keybinds.kdl` + +| Keybind | Action | IPC Command | +|---------|--------|-------------| +| `Mod+Return` | Terminal | `spawn "ghostty"` | +| `Mod+CTRL+Return` | App Launcher | `noctalia-shell ipc call launcher toggle` | +| `Mod+B` | Browser | `spawn "firefox"` | +| `Mod+ALT+L` | Lock Screen | `noctalia-shell ipc call lockScreen lock` | +| `Mod+Shift+Q` | Session Menu | `noctalia-shell ipc call sessionMenu toggle` | +| `Mod+Shift+Escape` | Hotkey Overlay | `show-hotkey-overlay` | +| `Mod+E` | File Manager | `spawn "nautilus"` | + +### Media and Brightness + +| Key | Action | IPC Command | +|-----|--------|-------------| +| `XF86AudioRaiseVolume` | Volume Up | `volume increase` | +| `XF86AudioLowerVolume` | Volume Down | `volume decrease` | +| `XF86AudioMute` | Mute | `volume muteOutput` | +| `XF86AudioMicMute` | Mic Mute | `volume muteInput` | +| `XF86AudioPlay` | Play/Pause | `media playPause` | +| `XF86AudioNext` | Next Track | `media next` | +| `XF86AudioPrev` | Previous | `media previous` | +| `XF86MonBrightnessUp` | Brightness Up | `brightness increase` | +| `XF86MonBrightnessDown` | Brightness Down | `brightness decrease` | + +### Wallpaper + +The wallpaper layer is placed in the backdrop: + +```kdl +// In ~/.config/niri/cfg/rules.kdl +layer-rule { + match namespace="^noctalia-wallpaper*" + place-within-backdrop true +} +``` + +The background color is set to transparent to allow the wallpaper to show: + +```kdl +// In ~/.config/niri/cfg/layout.kdl +layout { + background-color "transparent" +} +``` + +--- + +## Dependencies + +| Package | Purpose | +|---------|---------| +| `noctalia-qs` / `qs` | Quickshell runtime | +| `imagemagick` | Image processing | +| `brightnessctl` | Brightness control | +| `ffmpeg` | Media processing | +| `qt6-multimedia` | Qt multimedia | +| `python` | Python runtime | +| `wlr-randr` | Display information | + +--- + +## See Also + +- [niri](niri/index.md) — Compositor configuration +- [[displays|displays]] — Display layout +- [[cachyos|cachyos]] — Operating system documentation diff --git a/omp-docs/tools/npx-skills/best-practices.md b/omp-docs/tools/npx-skills/best-practices.md new file mode 100644 index 0000000..1d87dc4 --- /dev/null +++ b/omp-docs/tools/npx-skills/best-practices.md @@ -0,0 +1,48 @@ +--- +type: guide +title: Skill Author Best Practices +description: Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm. +tags: + - unverified + - skills + - best-practices + - authoring +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Best Practices for Skill Authors + +## Description Writing + +1. **Be specific about capabilities** — "Extracts text and tables from PDF files, fills forms, merges documents" vs "Helps with documents" +2. **Include trigger phrases** — "Use when working with PDF files or when user mentions PDFs, forms, or document extraction" +3. **Keep under 1024 characters** +4. **Write in third person** +5. **First sentence = what it does, second sentence = when to use it** + +## File Organization + +1. **Use progressive disclosure** — Keep SKILL.md focused; reference detailed docs in `references/` +2. **Add scripts for deterministic operations** — When the same code would be generated repeatedly, scripts save tokens and improve reliability +3. **Split files when content exceeds ~500 lines** — Agents load the entire file on activation +4. **Include a config.json** for configurable paths or settings +5. **Add tests** — Include test scripts and mock data for validation + +## Security + +1. **Review skill content before use** — Skills can instruct the model to perform any action +2. **Scripts run with your full system permissions** — Only install from trusted sources +3. **Document dependencies clearly** — List all required tools, API keys, and setup steps + +## Distribution + +1. **Add `pi-package` keyword** to package.json for npm discoverability +2. **Include `video` or `image` fields** in the pi manifest for the gallery +3. **Use peerDependencies** for pi-provided packages: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `typebox` +4. **List runtime deps in `dependencies`** — They get installed automatically + +## Related + +* [Package Structure](/tools/npx-skills/package-structure.md) — How to structure your npm package +* [Installation](/tools/npx-skills/installation.md) — How users will install your skills diff --git a/omp-docs/tools/npx-skills/ecosystem.md b/omp-docs/tools/npx-skills/ecosystem.md new file mode 100644 index 0000000..6d34463 --- /dev/null +++ b/omp-docs/tools/npx-skills/ecosystem.md @@ -0,0 +1,62 @@ +--- +type: reference +title: Ecosystem Resources +description: GitHub repositories, npm packages, and community resources for the pi skills ecosystem. +tags: + - unverified + - ecosystem + - npm + - repositories + - community +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Ecosystem Resources + +## Official Documentation + +- [Pi Skills Documentation](https://github.com/earendil-works/pi) +- [Pi Packages Documentation](https://github.com/earendil-works/pi) +- [Agent Skills Specification](https://agentskills.io/specification) +- [Agent Skills Integration Guide](https://agentskills.io/integrate-skills) +- [Pi Packages Gallery](https://pi.dev/packages) + +## GitHub Repositories + +| Repository | Description | Stars | +|------------|-------------|-------| +| [badlogic/pi-skills](https://github.com/badlogic/pi-skills) | Official skills collection (brave-search, browser-tools, Google APIs, transcription) | 2,138 | +| [ifiokjr/monopi](https://github.com/ifiokjr/monopi) | One-click pi setup with skills, extensions, themes, subagents | 136 | +| [VenTheZone/pi-dots](https://github.com/VenTheZone/pi-dots) | 60+ skills covering research, content, project management, debugging | 42 | +| [HazAT/pi-config](https://github.com/HazAT/pi-config) | Personal pi config with skills, extensions, agents | 418 | +| [qualisero/awesome-pi-agent](https://github.com/qualisero/awesome-pi-agent) | Awesome list of pi add-ons, hooks, tools, skills | 1,093 | +| [getpipher/pi-package-index](https://github.com/getpipher/pi-package-index) | Unofficial community index with GitHub stars + downloads | 2 | +| [lukaspanni/pi-package-template](https://github.com/lukaspanni/pi-package-template) | Template for creating pi packages | 0 | + +## Notable npm Packages + +| Package | Description | Keywords | +|---------|-------------|----------| +| `pi-web-access` | Web search, URL fetching, PDF extraction, YouTube analysis | pi-package, web-search, perplexity | +| `@wierdbytes/pi-peon` | Sound-pack player for pi (installed) | pi-package, peon, sound | +| `bigpowers` | 73 agent skills for solo developers | skills, agents, claude, pi-package | +| `pi-spark` | Polishes daily pi experience | pi-coding-agent, pi-package | +| `@anton-kochev/pi-skills` | Planning, TDD, SRS, requirements skills | pi-package, pi-skill, tdd | +| `@monopi/skills` | Curated skill packs (debug-helper, btw, nushell) | pi-package, skills | +| `@dietrichgebert/ponytail` | Lazy senior dev mode with skills | opencode, pi-package, skills | +| `pi-mcp-adapter` | MCP adapter for pi | pi-package, mcp | +| `pi-subagents` | Subagent delegation with chains | pi-package, subagents | +| `pi-lens` | Real-time code feedback (LSP, linters) | pi-package, linter | +| `@vanillagreen/pi-skills-manager` | Skills manager with /skill menu | pi-package, skills, manager | + +## Community Resources + +- [pi-package.rectorspace.com](https://pi-package.rectorspace.com) — Unofficial package index with stars, downloads, maintenance signals +- [Anthropic Skills](https://github.com/anthropics/skills) — Document processing skills (docx, pdf, pptx, xlsx) +- [skills.sh](https://skills.sh) — Skills directory (by Vercel Labs) + +## Related + +* [Installation](/tools/npx-skills/installation.md) — How to install from these resources +* [Best Practices](/tools/npx-skills/best-practices.md) — How to contribute your own skills diff --git a/omp-docs/tools/npx-skills/index.md b/omp-docs/tools/npx-skills/index.md new file mode 100644 index 0000000..1808b41 --- /dev/null +++ b/omp-docs/tools/npx-skills/index.md @@ -0,0 +1,18 @@ +# Npx Skills — Distribution & Installation + +Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm. + +## Concept Files + +| File | Type | Description | +|------|------|-------------| +| [best-practices.md](best-practices.md) | best-practices | Tips for writing good skill descriptions, organizing files, and distributing ... | +| [ecosystem.md](ecosystem.md) | reference | GitHub repositories, npm packages, and community resources for the pi skills ... | +| [installation.md](installation.md) | howto | Three methods for installing skills — pi install, npx-based setup tools, and ... | +| [package-structure.md](package-structure.md) | reference | How pi packages bundle skills, extensions, prompts, and themes into a single ... | +| [skill-commands.md](skill-commands.md) | reference | The /skill:name command system for explicitly loading and executing skills wi... | +| [skill-file-structure.md](skill-file-structure.md) | reference | The directory structure of a skill — SKILL.md as the required entry point, wi... | +| [skill-loading.md](skill-loading.md) | reference | The discovery flow, progressive disclosure pattern, and system prompt integra... | +| [skills-spec.md](skills-spec.md) | reference | The Agent Skills standard that defines SKILL.md format, frontmatter fields, a... | +| [skills-vs-extensions.md](skills-vs-extensions.md) | comparison | Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-... | + diff --git a/omp-docs/tools/npx-skills/installation.md b/omp-docs/tools/npx-skills/installation.md new file mode 100644 index 0000000..022ed02 --- /dev/null +++ b/omp-docs/tools/npx-skills/installation.md @@ -0,0 +1,81 @@ +--- +type: howto +title: Installing Skills via npm / npx +description: Three methods for installing skills — pi install, npx-based setup tools, and manual git clone. +tags: + - unverified + - installation + - npm + - npx +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Installing Skills via NPM / Npx + +## Method 1: Direct `pi install` (recommended) + +```bash +# Install a package containing skills +pi install npm:pi-web-access +pi install npm:@anton-kochev/pi-skills +pi install npm:bigpowers +pi install npm:@monopi/skills + +# Install from GitHub (also works for packages with skills) +pi install git:github.com/badlogic/pi-skills +pi install https://github.com/badlogic/pi-skills + +# Project-level install (goes to .pi/settings.json) +pi install -l npm:pi-web-access + +# Try without installing (current session only) +pi -e npm:pi-web-access +``` + +## Method 2: Npx-based setup tools + +Some meta-installers provide one-command setup: + +```bash +# monopi: one-command setup for pi with skills, extensions, themes, etc. +npx @monopi/monopi + +# Pin a version +npx @monopi/monopi --version 0.2.13 + +# Project-local install +npx @monopi/monopi --local + +# Remove all monopi packages +npx @monopi/monopi --remove +``` + +## Method 3: Manual clone (git repos) + +```bash +# Clone the official pi-skills collection +git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills + +# Or project-level +git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills +``` + +## Package Sources + +| Source Type | Example | Notes | +|-------------|---------|-------| +| **npm** | `npm:@foo/bar@1.0.0` | Pinned versions, installed to `~/.pi/agent/npm/` | +| **git** | `git:github.com/user/repo@v1` | Pinned to tags/commits, cloned to `~/.pi/agent/git/` | +| **local** | `./relative/path` | Points to local directory, added without copying | + +## Dependencies + +- Runtime dependencies belong in `dependencies` in `package.json` +- Pi-provided packages (`@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`) as `peerDependencies` with `"*"` range +- When pi installs from npm or git, it runs `npm install` automatically + +## Related + +* [Package Structure](/tools/npx-skills/package-structure.md) — How pi packages are structured for npm distribution +* [Best Practices](/tools/npx-skills/best-practices.md) — Distribution tips for skill authors diff --git a/omp-docs/tools/npx-skills/package-structure.md b/omp-docs/tools/npx-skills/package-structure.md new file mode 100644 index 0000000..f7b29ab --- /dev/null +++ b/omp-docs/tools/npx-skills/package-structure.md @@ -0,0 +1,79 @@ +--- +type: reference +title: Pi Package Structure +description: How pi packages bundle skills, extensions, prompts, and themes into a single npm package with a pi manifest. +tags: + - unverified + - packages + - npm + - distribution +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Pi Packages — The Distribution Mechanism + +Pi packages are npm packages that declare resources via a `pi` manifest in `package.json`. They are the primary way to distribute skills (along with extensions, prompts, and themes) through npm. + +## Package Structure + +``` +my-pi-package/ +├── package.json # npm metadata + pi manifest +├── skills/ # Conventional directory (auto-discovered) +│ ├── my-skill/ +│ │ └── SKILL.md +│ └── another-skill/ +│ └── SKILL.md +├── extensions/ # TypeScript extensions +├── prompts/ # Prompt templates +├── themes/ # TUI themes +└── README.md +``` + +## Package.json with pi Manifest + +```json +{ + "name": "my-pi-package", + "keywords": ["pi-package"], + "pi": { + "extensions": ["./extensions"], + "skills": ["./skills"], + "prompts": ["./prompts"], + "themes": ["./themes"] + } +} +``` + +## Gallery Metadata + +Packages tagged with `pi-package` appear on the [pi.dev/packages gallery](https://pi.dev/packages). Add preview media: + +```json +{ + "pi": { + "skills": ["./skills"], + "video": "https://example.com/demo.mp4", + "image": "https://example.com/screenshot.png" + } +} +``` + +## Two-Layer Model + +``` +npm package (tagged pi-package) +├── pi.skills manifest → points to ./skills/ +└── skills/ + ├── brave-search/SKILL.md + ├── browser-tools/SKILL.md + └── tdd-workflow/SKILL.md +``` + +Skills are the **content** (SKILL.md + scripts). Pi packages are the **delivery mechanism** (npm tarball with a `pi` manifest). + +## Related + +* [Installation](/tools/npx-skills/installation.md) — How to install pi packages +* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — What goes inside a skill diff --git a/omp-docs/tools/npx-skills/skill-commands.md b/omp-docs/tools/npx-skills/skill-commands.md new file mode 100644 index 0000000..35d7a8a --- /dev/null +++ b/omp-docs/tools/npx-skills/skill-commands.md @@ -0,0 +1,35 @@ +--- +type: reference +title: Skill Commands +description: The /skill:name command system for explicitly loading and executing skills with optional arguments. +tags: + - unverified + - skills + - commands +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Skill Commands (`/skill:name`) + +Skills register as `/skill:name` commands: + +```bash +/skill:brave-search # Load and execute the skill +/skill:pdf-tools extract # Load skill with arguments +``` + +Arguments after the command are appended to the skill content as `User: `. + +Toggle skill commands via `/settings` in interactive mode or in `settings.json`: + +```json +{ + "enableSkillCommands": true +} +``` + +## Related + +* [Skill Loading](../npx-skills/skill-loading.md) — How skills are normally loaded +* [Npx Skills Overview](../npx-skills/index.md) — Settings and package control diff --git a/omp-docs/tools/npx-skills/skill-file-structure.md b/omp-docs/tools/npx-skills/skill-file-structure.md new file mode 100644 index 0000000..199ffa2 --- /dev/null +++ b/omp-docs/tools/npx-skills/skill-file-structure.md @@ -0,0 +1,65 @@ +--- +type: reference +title: Skill File Structure +description: The directory structure of a skill — SKILL.md as the required entry point, with optional scripts, references, and assets directories. +tags: + - unverified + - skills + - structure + - SKILL.md +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Skill File Structure + +A skill is a **directory** with a `SKILL.md` file. Everything else is freeform. + +## Standard Structure + +``` +my-skill/ +├── SKILL.md # Required: frontmatter + instructions +├── scripts/ # Helper scripts (bash, js, python, etc.) +│ ├── process.sh +│ └── analyze.js +├── references/ # Detailed docs loaded on-demand +│ ├── api-reference.md +│ └── FORMS.md +├── assets/ # Templates, configs, binary data +│ └── template.json +├── config.json # Skill-specific configuration +└── tests/ # Test scripts (optional) + └── test_runner.sh +``` + +## Real Example: zim-knowledge-base + +``` +zim-knowledge-base/ +├── SKILL.md # Main skill instructions +├── config.json # ZIM file path configuration +├── scripts/ +│ ├── search.sh # Search ZIM file index +│ ├── extract.sh # Extract article as HTML +│ ├── list.sh # List article titles +│ └── metadata.sh # Get article metadata +└── tests/ + ├── mock_zimdump.sh # Mock for testing + ├── test_runner.sh # Test harness + └── test_zim_file.zim # Test fixture +``` + +## Real Example: brave-search (from badlogic/pi-skills) + +``` +brave-search/ +├── SKILL.md # Setup + usage instructions +├── search.js # Brave Search API wrapper +└── content.js # Page content extraction +``` + +## Related + +* [Skills Specification](/tools/npx-skills/skills-spec.md) — Frontmatter fields and requirements +* [Best Practices](/tools/npx-skills/best-practices.md) — File organization tips diff --git a/omp-docs/tools/npx-skills/skill-loading.md b/omp-docs/tools/npx-skills/skill-loading.md new file mode 100644 index 0000000..8635fef --- /dev/null +++ b/omp-docs/tools/npx-skills/skill-loading.md @@ -0,0 +1,42 @@ +--- +type: reference +title: How Pi Loads Skills +description: The discovery flow, progressive disclosure pattern, and system prompt integration for skills in pi. +tags: + - unverified + - skills + - loading + - progressive-disclosure +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# How the Pi Agent Loads and Uses Skills + +## Discovery Flow + +1. Pi scans all configured skill locations at startup +2. Extracts names and descriptions from each `SKILL.md` +3. Builds the system prompt with skill descriptions in XML format +4. The LLM decides which skill(s) to activate based on the user's prompt +5. When activated, the agent reads the full SKILL.md using the `read` tool + +## Progressive Disclosure Pattern + +``` +System prompt (always in context): + - "Available skills: brave-search (Web search...), browser-tools (Browser automation...), ..." + +User: "Search for information about React hooks" + +Agent decides: activate brave-search +Agent reads: ~/.pi/agent/skills/brave-search/SKILL.md (full file) +Agent executes: {baseDir}/search.js "React hooks" +``` + +## This is progressive disclosure: only descriptions are always in context, full instructions load on-demand. + +## Related + +* [Skills Specification](/tools/npx-skills/skills-spec.md) — What the agent sees in the system prompt +* [Skill Commands](/tools/npx-skills/skill-commands.md) — The `/skill:name` override diff --git a/omp-docs/tools/npx-skills/skills-spec.md b/omp-docs/tools/npx-skills/skills-spec.md new file mode 100644 index 0000000..342a42c --- /dev/null +++ b/omp-docs/tools/npx-skills/skills-spec.md @@ -0,0 +1,70 @@ +--- +type: reference +title: Agent Skills Specification +description: The Agent Skills standard that defines SKILL.md format, frontmatter fields, and cross-agent compatibility. +tags: + - unverified + - agent-skills + - specification + - npm +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Agent Skills Specification + +Pi implements the [Agent Skills standard](https://agentskills.io/specification), warning about most violations but remaining lenient. The specification defines: + +- A **frontmatter block** (YAML) at the top of `SKILL.md` with required `name` and `description` fields +- A **Markdown body** with the skill's instructions +- Optional subdirectories: `scripts/`, `references/`, `assets/` + +The specification is designed to be **cross-agent-compatible**: skills written for pi work with Claude Code, Codex CLI, Amp, Droid, and other compatible agents. + +## Frontmatter Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | **Yes** | Max 64 chars. Lowercase a-z, 0-9, hyphens only. No leading/trailing hyphens. No consecutive hyphens. | +| `description` | **Yes** | Max 1024 chars. What the skill does and when to use it. **This is the only thing the agent sees when deciding whether to activate the skill.** | +| `license` | No | License name or reference to bundled file. | +| `compatibility` | No | Max 500 chars. Environment requirements. | +| `metadata` | No | Arbitrary key-value mapping. | +| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). | +| `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly. | + +### Name Rules + +Valid: `pdf-processing`, `data-analysis`, `code-review` +Invalid: `PDF-Processing`, `-pdf`, `pdf--processing` + +**Note:** Pi does not require the name to match the parent directory. The Agent Skills standard does, but that requirement is suboptimal for shared skill directories. + +### Description Best Practices + +The description determines when the agent loads the skill. Be specific. + +**Good:** +```yaml +description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents. +``` + +**Poor:** +```yaml +description: Helps with PDFs. +``` + +## Cross-Agent Compatibility + +Skills follow a shared specification that works across: + +- Pi (`~/.pi/agent/skills/`) +- Claude Code (`~/.claude/skills/`) +- Codex (`~/.codex/skills/`) +- OpenCode (`~/.config/opencode/skills/`) +- And [68+ other agents](/tools/vercel-labs-skills/agent-support.md) + +## Related + +* [Skill File Structure](/tools/npx-skills/skill-file-structure.md) — How to organize SKILL.md and its supporting files +* [Ecosystem](/tools/npx-skills/ecosystem.md) — Where to find community skills diff --git a/omp-docs/tools/npx-skills/skills-vs-extensions.md b/omp-docs/tools/npx-skills/skills-vs-extensions.md new file mode 100644 index 0000000..852ca95 --- /dev/null +++ b/omp-docs/tools/npx-skills/skills-vs-extensions.md @@ -0,0 +1,50 @@ +--- +type: reference +title: Skills vs Extensions +description: Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-based) for pi coding agent. +tags: + - unverified + - skills + - extensions + - comparison +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Skills vs Extensions + +| Feature | Skills | Extensions | +|---------|--------|------------| +| **Format** | Markdown (`SKILL.md` + optional scripts) | TypeScript (`.ts` files) | +| **Purpose** | Instructions for the LLM to follow | Code that intercepts events, registers tools/commands | +| **Execution** | Agent reads and follows instructions | Runs in pi's Node.js runtime | +| **Loading** | On-demand (progressive disclosure) | Always loaded at startup | +| **Power** | Can instruct the agent to run anything | Full programmatic access to pi's API | +| **Security** | Review content (instructs model) | Review code (runs arbitrary code) | +| **Best for** | Domain knowledge, workflows, scripts | Permission gates, custom tools, event handling | +| **Location** | `skills/` directory | `extensions/` directory | +| **Can distribute via npm?** | Yes (via pi packages) | Yes (via pi packages) | + +## When to Use Each + +- **Skill**: You want to teach the agent a new workflow, provide domain expertise, or bundle helper scripts +- **Extension**: You need to intercept tool calls, register new LLM-callable tools, modify system prompts programmatically, or add custom TUI components + +## They Can Work Together + +A pi package can contain both: + +```json +{ + "pi": { + "extensions": ["./extensions"], + "skills": ["./skills"] + } +} +``` + +Example: `pi-web-access` provides both a web-search extension AND skill documentation for it. + +## Related + +* [Package Structure](/tools/npx-skills/package-structure.md) — How to bundle both in one npm package diff --git a/omp-docs/tools/ornith-llama-cpp-setup/api-endpoints.md b/omp-docs/tools/ornith-llama-cpp-setup/api-endpoints.md new file mode 100644 index 0000000..b73b984 --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/api-endpoints.md @@ -0,0 +1,73 @@ +--- +type: reference +title: llama.cpp Server API Endpoints +description: Complete reference for health check, model listing, chat completions, and native completion endpoints. +tags: + - unverified + - ornith + - api + - llama.cpp + - endpoints +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# API Endpoints + +The llama.cpp server provides these endpoints: + +## Health Check + +```bash +curl http://localhost:8080/health +``` + +## List Models + +```bash +curl http://localhost:8080/v1/models +``` + +## Chat Completions (OpenAI-compatible) + +```bash +curl http://localhost:8080/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{ + "model": "frank-default-local", + "messages": [...], + "max_tokens": 100 + }' +``` + +## Native Completion Endpoint + +```bash +curl http://localhost:8080/completion \ + -H "Content-Type: application/json" \ + -d '{ + "prompt": "Hello, how are you?", + "n_predict": 100 + }' +``` + +## Model Features + +### Reasoning/Thinking Blocks + +Ornith models use `...` blocks for reasoning. The server automatically: +- Detects and preserves reasoning content +- Returns reasoning in `reasoning_content` field +- Supports the `developer` role (or falls back to `system`) + +### Chat Template + +The model uses a specific chat template that supports: +- System prompts +- User/Assistant roles +- Reasoning preservation + +## Related + +* [Pi Configuration](/tools/ornith-llama-cpp-setup/pi-configuration.md) — How pi connects to these endpoints +* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — Starting the server diff --git a/omp-docs/tools/ornith-llama-cpp-setup/gpu-offloading.md b/omp-docs/tools/ornith-llama-cpp-setup/gpu-offloading.md new file mode 100644 index 0000000..5b6930e --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/gpu-offloading.md @@ -0,0 +1,46 @@ +--- +type: reference +title: GPU Layer Offloading Guidelines +description: How many GPU layers to offload based on your VRAM size for both Ornith 9B and 35B models. +tags: + - unverified + - ornith + - gpu + - offloading + - llama.cpp +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# GPU Layer Offloading + +## For 9B Q4_K_M (5.63 GB): + +- **8GB VRAM:** `-ngl 35-40` (fits most layers) +- **12GB VRAM:** `-ngl 99` (all layers) +- **16GB+ VRAM:** `-ngl 99` (all layers + room for large KV cache) + +## For 35B Q4_K_M (~20 GB): + +- **8GB VRAM:** `-ngl 10-14` (partial offload) +- **12GB VRAM:** `-ngl 18-22` (partial offload) +- **16GB VRAM:** `-ngl 28-32` (partial offload) +- **24GB VRAM:** `-ngl 40-48` (majority of layers) +- **40GB+ VRAM:** `-ngl 99` (all layers) + +**Note:** The 35B model is a MoE architecture, so actual memory usage depends on which experts are activated. + +## Context Window Considerations + +- **9B model:** Supports up to 262,144 tokens +- **35B model:** Supports up to 262,144 tokens +- **KV Cache Memory:** Larger context windows require more VRAM/RAM for the key-value cache + - 131K context: ~8-16 GB depending on model and quantization + - 256K context: ~16-32 GB depending on model and quantization + +**Recommendation:** Start with 131K context if you have limited VRAM, increase to 256K if you have headroom. + +## Related + +* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — How to set the -ngl flag +* [Model Specs](/tools/ornith-llama-cpp-setup/model-specs.md) — Memory requirements diff --git a/omp-docs/tools/ornith-llama-cpp-setup/index.md b/omp-docs/tools/ornith-llama-cpp-setup/index.md new file mode 100644 index 0000000..b5569bf --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/index.md @@ -0,0 +1,17 @@ +# Ornith llama.cpp Setup + +Complete reference for running Ornith-9B/35B MoE models with llama.cpp server on dankware. + +## Concept Files + +| File | Type | Description | +|------|------|-------------| +| [api-endpoints.md](api-endpoints.md) | reference | Complete reference for health check, model listing, chat completions, and nat... | +| [gpu-offloading.md](gpu-offloading.md) | reference | How many GPU layers to offload based on your VRAM size for both Ornith 9B and... | +| [installation.md](installation.md) | howto | Step-by-step setup — clone and build llama.cpp, download models, start the se... | +| [model-specs.md](model-specs.md) | reference | Specifications for Ornith-1.0-9B dense and Ornith-1.0-35B MoE models — contex... | +| [performance.md](performance.md) | reference | Token throughput benchmarks for Ornith 9B and 35B models with GPU vs CPU infe... | +| [pi-configuration.md](pi-configuration.md) | howto | How to add Ornith models to models.json so pi can use the local llama.cpp ser... | +| [systemd-service.md](systemd-service.md) | howto | Set up llama.cpp server as a background service with systemd for persistent o... | +| [troubleshooting.md](troubleshooting.md) | howto | Common errors — CUDA OOM, segfaults, model not responding, poor performance —... | + diff --git a/omp-docs/tools/ornith-llama-cpp-setup/installation.md b/omp-docs/tools/ornith-llama-cpp-setup/installation.md new file mode 100644 index 0000000..7c2683d --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/installation.md @@ -0,0 +1,97 @@ +--- +type: howto +title: Installing Ornith + llama.cpp +description: Step-by-step setup — clone and build llama.cpp, download models, start the server, verify it works. +tags: + - ornith + - installation + - llama.cpp + - unverified +verified: 2026-08-28 +--- + +# Installation + +## 1. Clone and Build llama.cpp + +```bash +cd ~/GitPackages +git clone https://github.com/ggerganov/llama.cpp +cd llama.cpp +cmake -B build -DLLAMA_CUDA=ON +cmake --build build --config Release +``` + +## 2. Download the Model + +```bash +mkdir -p ~/models/ornith +cd ~/models/ornith + +# For 9B model (faster, less memory) +wget https://huggingface.co/ornith-ai/Ornith-1.0-9B-GGUF/resolve/main/ornith-1.0-9b-Q4_K_M.gguf + +# OR for 35B MoE model (better performance, more memory) +wget https://huggingface.co/ornith-ai/Ornith-1.0-35B-GGUF/resolve/main/ornith-1.0-35b-Q4_K_M.gguf +``` + +## 3. Start the Server + +**For 9B model with full GPU offload (8GB+ VRAM):** +```bash +cd ~/GitPackages/llama.cpp +./build/bin/llama-server \ + -m ~/models/ornith/ornith-1.0-9b-Q4_K_M.gguf \ + -c 262144 \ + -ngl 99 \ + --host 0.0.0.0 \ + --port 8080 +``` + +**For 35B MoE model with partial GPU offload (8GB VRAM example):** +```bash +cd ~/GitPackages/llama.cpp +./build/bin/llama-server \ + -m ~/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \ + -c 131072 \ + -ngl 12 \ + --host 0.0.0.0 \ + --port 8080 +``` + +**Key Parameters:** +- `-m`: Path to GGUF model file +- `-c` / `--ctx-size`: Context window size (131072 or 262144) +- `-ngl` / `--n-gpu-layers`: Number of layers to offload to GPU + - 99 = all layers + - Lower values = more CPU inference +- `--host`: Bind address (0.0.0.0 for all interfaces, 127.0.0.1 for local only) +- `--port`: Server port (default 8080) + +## 4. Verify Server is Running + +```bash +curl http://localhost:8080/health +# Expected: {"status":"ok"} +``` + +## 5. Test the Model + +```bash +curl -s http://localhost:8080/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{ + "model": "frank-default-local", + "messages": [ + {"role": "user", "content": "Hello, what is 2+2?"} + ], + "max_tokens": 150, + "temperature": 0.7 + }' | jq . +``` + +## Related + +* [Model Specs](/tools/ornith-llama-cpp-setup/model-specs.md) — Model options and quantization +* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Tuning GPU layer counts +* [Pi Configuration](/tools/ornith-llama-cpp-setup/pi-configuration.md) — Adding to models.json diff --git a/omp-docs/tools/ornith-llama-cpp-setup/model-specs.md b/omp-docs/tools/ornith-llama-cpp-setup/model-specs.md new file mode 100644 index 0000000..829cdef --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/model-specs.md @@ -0,0 +1,65 @@ +--- +type: reference +title: Ornith Model Specifications +description: Specifications for Ornith-1.0-9B dense and Ornith-1.0-35B MoE models — context length, quantization options, memory requirements. +tags: + - ornith + - models + - llama.cpp + - GGUF + - unverified +verified: 2026-08-28 +--- + +# Model Specifications + +## Ornith-1.0-9B-GGUF + +- **Source:** https://huggingface.co/ornith-ai/Ornith-1.0-9B-GGUF +- **Architecture:** Dense ~9B model +- **Context Length:** 262,144 tokens (256K) +- **Quantization Options:** + - Q4_K_M: 5.3 GB (recommended for most systems) + - Q5_K_M: 6.47 GB + - Q6_K: 7.36 GB + - Q8_0: 9.53 GB + - bf16: 17.9 GB + +## Ornith-1.0-35B-GGUF (MoE) + +- **Source:** https://huggingface.co/ornith-ai/Ornith-1.0-35B-GGUF +- **Architecture:** 35B MoE (Mixture of Experts) +- **Context Length:** 262,144 tokens (256K) +- **Quantization Options:** + - Q4_K_M: 20 GB (recommended) + - Other quantizations available + +**Note:** No fp4 quantization exists for these models. Q4_K_M is the lightest quantization. + +## Comparison: 9B vs 35B MoE + +| Aspect | 9B Dense | 35B MoE | +|--------|----------|---------| +| **Memory (Q4)** | 5.3 GB | 20 GB | +| **VRAM for Full GPU** | 8 GB | 24-40 GB | +| **Speed (GPU)** | Faster | Slower but better quality | +| **Quality** | Good | Excellent | +| **Context** | 256K | 256K | +| **Best For** | Quick tasks, limited RAM | Complex reasoning, best quality | + +## Requirements + +### Hardware +- **RAM:** Minimum 16GB for 9B model, 32GB+ for 35B model +- **GPU** (optional but recommended): + - 9B Q4: 6-8GB VRAM for full GPU offload + - 35B Q4: 24GB+ VRAM for full GPU offload + +### Software +- llama.cpp built with CUDA support (for GPU acceleration) +- Git (for cloning llama.cpp repo) + +## Related + +* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — How to set up the server +* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Layer allocation by VRAM diff --git a/omp-docs/tools/ornith-llama-cpp-setup/performance.md b/omp-docs/tools/ornith-llama-cpp-setup/performance.md new file mode 100644 index 0000000..c691557 --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/performance.md @@ -0,0 +1,39 @@ +--- +type: reference +title: Performance Benchmarks +description: Token throughput benchmarks for Ornith 9B and 35B models with GPU vs CPU inference. +tags: + - ornith + - performance + - benchmarks + - unverified +verified: 2026-08-28 +--- + +# Performance +# Performance + +## 9B Model: + +- **Prompt Processing:** ~10-15 tokens/sec (CPU), ~50-100 tokens/sec (GPU) +- **Generation:** ~8-12 tokens/sec (CPU), ~40-80 tokens/sec (GPU) + +## 35B MoE Model: + +- **Prompt Processing:** ~5-8 tokens/sec (CPU+GPU mix), ~30-50 tokens/sec (full GPU) +- **Generation:** ~4-8 tokens/sec (CPU+GPU mix), ~20-40 tokens/sec (full GPU) + +**Note:** MoE models can be slower due to expert routing overhead, but provide better quality. + +## Tuning Tips + +1. **Increase GPU layers** (`-ngl`) for better speed +2. **Enable Flash Attention:** `--flash-attn on` (if supported) +3. **Use a smaller quantization** (Q4_K_M instead of Q8_0) +4. **Reduce context window size** if memory-bound +5. **KV Cache Quantization:** `--cache-type-k q8_0` to reduce KV cache memory + +## Related + +* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — Optimize GPU layers for your hardware +* [Troubleshooting](/tools/ornith-llama-cpp-setup/troubleshooting.md) — Fix performance issues diff --git a/omp-docs/tools/ornith-llama-cpp-setup/pi-configuration.md b/omp-docs/tools/ornith-llama-cpp-setup/pi-configuration.md new file mode 100644 index 0000000..dbec1b3 --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/pi-configuration.md @@ -0,0 +1,55 @@ +--- +type: howto +title: Pi Configuration for Ornith Models +description: How to add Ornith models to models.json so pi can use the local llama.cpp server as a provider. +tags: + - unverified + - ornith + - pi + - models.json + - configuration +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Pi Configuration + +Add to `~/.pi/agent/models.json`: + +```json +{ + "providers": { + "llamacpp (local-ornith)": { + "baseUrl": "http://localhost:8080/v1", + "api": "openai-completions", + "apiKey": "EMPTY", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + }, + "models": [ + { + "id": "frank-default-local", + "name": "Ornith-1.0-35B-Q4_K_M (Local)", + "contextWindow": 131072, + "reasoning": true, + "thinkingLevelMap": { + "max": "xhigh" + } + } + ] + } + } +} +``` + +**Important Compatibility Settings:** + +- `supportsDeveloperRole: false` — The server does not support the `developer` role, uses `system` instead +- `supportsReasoningEffort: false` — The server does not support the `reasoning_effort` parameter +- `reasoning: true` — Model supports reasoning/thinking blocks + +## Related + +* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — Get the server running first +* [API Endpoints](/tools/ornith-llama-cpp-setup/api-endpoints.md) — The endpoints this configuration targets diff --git a/omp-docs/tools/ornith-llama-cpp-setup/systemd-service.md b/omp-docs/tools/ornith-llama-cpp-setup/systemd-service.md new file mode 100644 index 0000000..3a62e2e --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/systemd-service.md @@ -0,0 +1,59 @@ +--- +type: howto +title: Running Ornith as a Systemd Service +description: Set up llama.cpp server as a background service with systemd for persistent operation. +tags: + - unverified + - ornith + - systemd + - service +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Systemd Service + +## Using nohup: + +```bash +nohup ~/GitPackages/llama.cpp/build/bin/llama-server \ + -m ~/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \ + -c 131072 -ngl 12 \ + --host 0.0.0.0 --port 8080 \ + > ~/logs/llama-server.log 2>&1 & +``` + +## Using systemd (advanced): + +Create `/etc/systemd/system/llama-server.service`: + +```ini +[Unit] +Description=llama.cpp Server +After=network.target + +[Service] +Type=simple +User=dank +ExecStart=/home/dank/GitPackages/llama.cpp/build/bin/llama-server \ + -m /home/dank/models/ornith/ornith-1.0-35b-Q4_K_M.gguf \ + -c 131072 -ngl 12 \ + --host 0.0.0.0 --port 8080 +Restart=on-failure +WorkingDirectory=/home/dank/GitPackages/llama.cpp + +[Install] +WantedBy=multi-user.target +``` + +Then: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable llama-server +sudo systemctl start llama-server +``` + +## Related + +* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — The server setup this service wraps diff --git a/omp-docs/tools/ornith-llama-cpp-setup/troubleshooting.md b/omp-docs/tools/ornith-llama-cpp-setup/troubleshooting.md new file mode 100644 index 0000000..19fe432 --- /dev/null +++ b/omp-docs/tools/ornith-llama-cpp-setup/troubleshooting.md @@ -0,0 +1,71 @@ +--- +type: howto +title: Troubleshooting Ornith + llama.cpp +description: Common errors — CUDA OOM, segfaults, model not responding, poor performance — and their fixes. +tags: + - unverified + - ornith + - troubleshooting + - llama.cpp +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Troubleshooting + +## CUDA Out of Memory + +``` +Error: cudaMalloc failed: out of memory +``` + +**Solution:** Reduce `-ngl` value to offload fewer layers to GPU. + +## Segmentation Fault + +``` +Segmentation fault (core dumped) +``` + +**Solution:** +1. Reduce context size (`-c` parameter) +2. Reduce GPU layers (`-ngl`) +3. Check if model file is corrupted + +## Model Not Responding + +``` +curl: (7) Failed to connect to localhost port 8080 +``` + +**Solution:** Check if server is running: +```bash +ps aux | grep llama-server +tail -f ~/logs/llama-server.log +``` + +## Poor Performance + +**Solutions:** +1. Increase GPU layers (`-ngl`) +2. Enable Flash Attention: `--flash-attn on` (if supported) +3. Use a smaller quantization (Q4_K_M instead of Q8_0) +4. Reduce context window size + +## Security Considerations + +- **Local Server:** By default, binds to localhost (127.0.0.1) +- **Network Exposure:** If binding to 0.0.0.0, consider: + - Adding authentication (`--api-key`) + - Using a firewall to restrict access + - Running behind a reverse proxy with TLS + +```bash +# Add API key authentication +./build/bin/llama-server ... --api-key your-secret-key +``` + +## Related + +* [Installation](/tools/ornith-llama-cpp-setup/installation.md) — The commands that might be causing issues +* [GPU Offloading](/tools/ornith-llama-cpp-setup/gpu-offloading.md) — GPU configuration diff --git a/omp-docs/tools/tmux.md b/omp-docs/tools/tmux.md new file mode 100644 index 0000000..0dc25cb --- /dev/null +++ b/omp-docs/tools/tmux.md @@ -0,0 +1,409 @@ +--- +type: reference +title: tmux +description: Terminal multiplexer configuration, extended-keys setup, keyboard input best practices, and reload/restart procedures. +tags: + - terminal + - multiplexer + - tmux +timestamp: 2026-08-06 +--- + +# tmux Configuration Guide + +Complete reference for tmux keyboard configuration, extended-keys, and best practices. + +**Verified for tmux 3.6** (June 2026) + +--- + +## Table of Contents + +1. [Extended Keys Configuration](#extended-keys-configuration) +2. [Best Practices for Keyboard Input](#best-practices-for-keyboard-input) +3. [Reloading vs. Restarting tmux](#reloading-vs-restarting-tmux) +4. [Essential Configuration Reference](#essential-configuration-reference) +5. [Troubleshooting](#troubleshooting) + +--- + +## Extended Keys Configuration + +### What is `extended-keys`? + +The `extended-keys` option enables tmux to forward modified key combinations (keys pressed with Shift, Ctrl, Alt/Meta, or other modifiers) to applications running inside tmux. Without this configuration, tmux strips modifier information from certain keys by default. + +### Why is it needed? + +By default, tmux cannot distinguish between many modified key combinations: + +| Key | Without extended-keys | With extended-keys (csi-u) | +|-----|----------------------|---------------------------| +| Enter | `\r` | `\r` | +| Shift+Enter | `\r` (indistinguishable!) | `\x1b[13;2u` | +| Ctrl+Enter | `\r` (indistinguishable!) | `\x1b[13;5u` | +| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` | + +This affects: +- Applications that rely on modified Enter keys (like Pi, Neovim, etc.) +- Custom keybindings using Shift+Enter, Ctrl+Enter, etc. +- Any application using the Kitty keyboard protocol or CSI-u format + +### The Recommended Configuration + +Add these lines to `~/.tmux.conf`: + +```tmux +# Enable extended key reporting +set -g extended-keys on + +# Use CSI-u format (requires tmux 3.5+) +set -g extended-keys-format csi-u +``` + +### Why `csi-u` format is recommended + +tmux supports two formats for extended keys: + +1. **xterm (default)**: Uses `modifyOtherKeys` format + - `Ctrl+C` → `\x1b[27;5;99~` + - `Ctrl+D` → `\x1b[27;5;100~` + - `Ctrl+Enter` → `\x1b[27;5;13~` + +2. **csi-u (recommended)**: Uses CSI-u format + - `Ctrl+C` → `\x1b[99;5u` + - `Ctrl+D` → `\x1b[100;5u` + - `Ctrl+Enter` → `\x1b[13;5u` + +The `csi-u` format is more reliable and is the modern standard. Applications like Pi automatically request extended key reporting when Kitty keyboard protocol is not available. + +### Requirements + +- **tmux 3.5 or later** for `extended-keys-format csi-u` + - Check version: `tmux -V` + - For tmux 3.2–3.4, omit the `extended-keys-format` line. The default xterm format still works +- A terminal emulator that supports extended keys: + - Ghostty + - Kitty + - iTerm2 + - WezTerm + - Windows Terminal + +--- + +## Best Practices for Keyboard Input and Keybindings + +### Essential Settings + +```tmux +# Fix Vim ESC delay (tmux 3.5+ already defaults to 10ms) +set -sg escape-time 0 + +# Increase scrollback buffer +set -g history-limit 50000 + +# Start windows and panes at 1, not 0 +set -g base-index 1 +setw -g pane-base-index 1 + +# Enable mouse support +set -g mouse on + +# Enable focus events for vim autoread +set -g focus-events on + +# Set terminal with proper colors +set -g default-terminal "tmux-256color" +set -as terminal-features ",xterm-256color:RGB" + +# Aggressive resize for multi-client +setw -g aggressive-resize on +``` + +### Prefix Key Customization + +The default prefix `C-b` is awkward. Common alternatives: + +```tmux +# Option 1: Change to Ctrl+a (common, but conflicts with readline) +unbind C-b +set -g prefix C-a +bind-key C-a send-prefix + +# Option 2: Use Alt+w or another comfortable combination +set -g prefix M-w +bind-key M-w send-prefix +``` + +### Intuitive Split Commands + +Replace the default `"` and `%` with visual separators: + +```tmux +# Split panes using | and - +bind | split-window -h -c "#{pane_current_path}" +bind - split-window -v -c "#{pane_current_path}" +unbind '"' +unbind % +``` + +### Vim-Style Pane Navigation + +```tmux +# Switch panes using Alt+arrow without prefix +bind -n M-Left select-pane -L +bind -n M-Right select-pane -R +bind -n M-Up select-pane -U +bind -n M-Down select-pane -D + +# Or use vim-style hjkl (requires prefix) +bind h select-pane -L +bind j select-pane -D +bind k select-pane -U +bind l select-pane -R +``` + +### Copy Mode Configuration + +```tmux +# Use vi keys in copy mode +setw -g mode-keys vi + +# Vi-style copy bindings +bind -T copy-mode-vi v send -X begin-selection +bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i" # Linux +# bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy" # macOS +``` + +### Quick Config Reload Binding + +```tmux +# Reload config with C-a r (or your prefix + r) +bind r source-file ~/.tmux.conf \; display-message "Config reloaded!" +``` + +--- + +## Reloading vs. Restarting tmux + +### Reloading Configuration (Preserves Sessions) + +For most configuration changes, you can reload without losing sessions: + +**Method 1: Command-line** +```bash +tmux source-file ~/.tmux.conf +``` + +**Method 2: From within tmux** +1. Press your prefix key (default `C-b`) +2. Type `:` to open the command prompt +3. Enter: `source-file ~/.tmux.conf` + +**Method 3: Using a keybinding** (recommended) +```tmux +bind r source-file ~/.tmux.conf \; display-message "Config reloaded!" +``` +Then press `C-b r` (or your configured prefix + r). + +### When Full Restart is Required + +Some changes require a complete tmux server restart: + +- `extended-keys` and `extended-keys-format` changes +- `default-terminal` changes +- Server-level options like `message-limit` +- Changes to terminal features + +**Full restart procedure:** +```bash +# 1. Detach from current session (if attached) +# Press: C-b d + +# 2. Kill the tmux server (ends all sessions) +tmux kill-server + +# 3. Start fresh +tmux +``` + +**Alternative: Restart while preserving sessions** (tmux 3.2+) +```bash +# 1. Save session state (requires tmux-resurrect plugin) +# Press: C-a C-s + +# 2. Kill server +tmux kill-server + +# 3. Restart and restore +tmux +# Press: C-a C-r (to restore sessions) +``` + +### Quick Reference: Reload vs. Restart + +| Change Type | Reload OK? | Restart Required? | +|-------------|------------|-------------------| +| Keybindings | ✅ Yes | ❌ No | +| Status bar styles | ✅ Yes | ❌ No | +| Mouse settings | ✅ Yes | ❌ No | +| Copy mode bindings | ✅ Yes | ❌ No | +| `extended-keys` | ❌ No | ✅ Yes | +| `extended-keys-format` | ❌ No | ✅ Yes | +| `default-terminal` | ❌ No | ✅ Yes | +| `escape-time` | ⚠️ Sometimes | ✅ Yes (for full effect) | + +--- + +## Essential Configuration Reference + +### Complete Production-Ready `~/.tmux.conf` + +```tmux +# ============================================ +# ESSENTIAL SETTINGS +# ============================================ + +# Extended keys (required for modern applications) +set -g extended-keys on +set -g extended-keys-format csi-u + +# Fix Vim ESC delay +set -sg escape-time 0 + +# Increase scrollback buffer +set -g history-limit 50000 + +# Start windows and panes at 1, not 0 +set -g base-index 1 +setw -g pane-base-index 1 + +# Enable mouse support +set -g mouse on + +# Enable focus events for vim autoread +set -g focus-events on + +# Set terminal with proper colors +set -g default-terminal "tmux-256color" +set -as terminal-features ",xterm-256color:RGB" + +# Aggressive resize for multi-client +setw -g aggressive-resize on + +# ============================================ +# KEY BINDINGS +# ============================================ + +# Change prefix to Ctrl+a (more ergonomic) +unbind C-b +set -g prefix C-a +bind C-a send-prefix + +# Reload config +bind r source-file ~/.tmux.conf \; display "Config reloaded!" + +# Better pane splitting (and keep current path) +bind | split-window -h -c "#{pane_current_path}" +bind - split-window -v -c "#{pane_current_path}" +bind c new-window -c "#{pane_current_path}" + +# Vim-style pane navigation +bind h select-pane -L +bind j select-pane -D +bind k select-pane -U +bind l select-pane -R + +# Vim-style pane resizing +bind -r H resize-pane -L 5 +bind -r J resize-pane -D 5 +bind -r K resize-pane -U 5 +bind -r L resize-pane -R 5 + +# ============================================ +# COPY MODE +# ============================================ + +# Use vi keys +setw -g mode-keys vi + +# Vi-style copy bindings +bind -T copy-mode-vi v send -X begin-selection +# Linux: +bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i" +# macOS: +# bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy" +``` + +--- + +## Troubleshooting + +### Modified keys still not working + +1. **Check tmux version:** + ```bash + tmux -V + ``` + Must be 3.5+ for `extended-keys-format csi-u`. + +2. **Verify configuration is loaded:** + ```bash + tmux show-options -g extended-keys + tmux show-options -g extended-keys-format + ``` + +3. **Ensure terminal supports extended keys:** + - Test in Ghostty, Kitty, iTerm2, WezTerm, or Windows Terminal + - Some older terminals do not support the CSI-u format + +4. **Full restart required:** + ```bash + tmux kill-server + tmux + ``` + +### Configuration changes not taking effect + +- **Most changes:** Use `tmux source-file ~/.tmux.conf` +- **Extended keys changes:** Must restart with `tmux kill-server` +- **Check for errors:** Look at the first session created after restart for error messages + +### Escape key delay + +If you experience delay when pressing Escape: +```tmux +set -sg escape-time 0 +``` + +### Mouse scrolling not working in copy mode + +```tmux +bind -n WheelUpPane copy-mode -e +bind -n WheelDownPane copy-mode -e +``` + +### Clipboard not working + +For Linux: +```tmux +bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -selection clipboard -i" +``` + +For macOS: +```tmux +bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy" +``` + +--- + +## References + +- [tmux Manual Page](https://man7.org/linux/man-pages/man1/tmux.1.html) +- [tmux GitHub Wiki](https://github.com/tmux/tmux/wiki) +- [Pi tmux Setup Documentation](https://pi.dev/docs/latest/tmux) + +--- + +*Documentation last updated: June 2026* +*Tested with tmux 3.6b* diff --git a/omp-docs/tools/vercel-labs-skills/agent-support.md b/omp-docs/tools/vercel-labs-skills/agent-support.md new file mode 100644 index 0000000..23265ee --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/agent-support.md @@ -0,0 +1,84 @@ +--- +type: reference +title: Skills CLI Agent Support Matrix +description: Complete list of 68+ supported coding agents, their --agent flags, and installation paths (project and global). +tags: + - unverified + - skills + - agents + - compatibility +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Agent Support + +The CLI supports **68+ agents**. It automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select which agents to install to. + +## Full Agent Path Table + +| Agent | `--agent` | Project Path | Global Path | +|-------|-----------|--------------|-------------| +| Amp, Replit, Universal | `amp`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` | +| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` | +| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` | +| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` | +| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` | +| Cline, Dexto, Kimi Code CLI, Loaf, Warp, Zed | `cline`, `dexto`, `kimi-code-cli`, `loaf`, `warp`, `zed` | `.agents/skills/` | `~/.agents/skills/` | +| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` | +| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` | +| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` | +| Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` | +| Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | +| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` | +| Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` | +| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` | +| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` | +| Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` | +| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` | +| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` | +| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` | +| Deep Agents | `deepagents` | `.agents/skills/` | `~/.deepagents/agent/skills/` | +| Droid / Factory AI | `droid` | `.factory/skills/` | `~/.factory/skills/` | +| Firebender | `firebender` | `.agents/skills/` | `~/.firebender/skills/` | +| Devin for Terminal | `devin` | `.devin/skills/` | `~/.config/devin/skills/` | +| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` | +| Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` | +| Anthropic Antigravity | `antigravity` | `.agents/skills/` | `~/.gemini/antigravity/skills/` | +| Jazz | `jazz` | `.jazz/skills/` | `~/.jazz/skills/` | +| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` | +| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` | +| Lingma | `lingma` | `.lingma/skills/` | `~/.lingma/skills/` | +| Moxby | `moxby` | `.moxby/skills/` | `~/.moxby/skills/` | +| Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` | +| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` | +| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` | +| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` | +| AiderDesk | `aider-desk` | `.aider-desk/skills/` | `~/.aider-desk/skills/` | +| IBM Bob | `bob` | `.bob/skills/` | `~/.bob/skills/` | +| CodeArts Agent | `codearts-agent` | `.codeartsdoer/skills/` | `~/.codeartsdoer/skills/` | +| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` | +| Codemaker | `codemaker` | `.codemaker/skills/` | `~/.codemaker/skills/` | +| Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` | +| Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` | +| Eve | `eve` | `agent/skills/` | N/A (project-only) | +| ForgeCode | `forgecode` | `.forge/skills/` | `~/.forge/skills/` | +| Hermes Agent | `hermes-agent` | `.hermes/skills/` | `~/.hermes/skills/` | +| inference.sh | `inference-sh` | `.inferencesh/skills/` | `~/.inferencesh/skills/` | +| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` | +| MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` | +| Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` | +| Ona | `ona` | `.ona/skills/` | `~/.ona/skills/` | +| PromptScript | `promptscript` | `.agents/skills/` | N/A (project-only) | +| Reasonix | `reasonix` | `.reasonix/skills/` | `~/.reasonix/skills/` | +| Rovo Dev | `rovodev` | `.rovodev/skills/` | `~/.rovodev/skills/` | +| Tabnine CLI | `tabnine-cli` | `.tabnine/agent/skills/` | `~/.tabnine/agent/skills/` | +| Terramind | `terramind` | `.terramind/skills/` | `~/.terramind/skills/` | +| Tinycloud | `tinycloud` | `.tinycloud/skills/` | `~/.tinycloud/skills/` | +| Zencoder, Zenflow | `zencoder`, `zenflow` | `.zencoder/skills/` | `~/.zencoder/skills/` | + +> **Kiro CLI users:** The default agent automatically loads skills from `.kiro/skills/` and `~/.kiro/skills/` — no configuration needed. + +## Related + +* [Commands](/tools/vercel-labs-skills/commands.md) — Using the `--agent` flag with commands diff --git a/omp-docs/tools/vercel-labs-skills/commands.md b/omp-docs/tools/vercel-labs-skills/commands.md new file mode 100644 index 0000000..42c154e --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/commands.md @@ -0,0 +1,116 @@ +--- +type: reference +title: Skills CLI Commands +description: Complete reference for all skills CLI commands — add, use, list, find, update, remove, init, experimental_install, experimental_sync. +tags: + - unverified + - skills + - cli + - commands +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Commands Reference + +## `skills add` — Install Skills + +Install skills from a source (git repo, URL, or local path) into your agent directories. + +```bash +npx skills add [options] +``` + +### Options + +| Option | Description | +|--------|-------------| +| `-g, --global` | Install to user directory (`~/`) instead of project (`./`) | +| `-a, --agent ` | Target specific agents | +| `-s, --skill ` | Install specific skills by name. Use `'*'` for all. | +| `-l, --list` | List available skills without installing | +| `--copy` | Copy files instead of symlinking | +| `-y, --yes` | Skip all confirmation prompts | +| `--all` | Install all skills to all agents without prompts | + +### Examples + +```bash +npx skills add vercel-labs/agent-skills --list +npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator +npx skills add vercel-labs/agent-skills -a claude-code -a opencode +npx skills add vercel-labs/agent-skills --all +``` + +## `skills use` — Use Without Installing + +Generate a prompt for one skill, or start a supported coding agent interactively with the skill loaded. + +```bash +npx skills use [options] +# Generate prompt only +npx skills use vercel-labs/agent-skills@web-design-guidelines | claude +# Use with specific agent +npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code +``` + +## `skills list` (alias: `ls`) — List Installed Skills + +```bash +npx skills list +npx skills ls -g # Global only +npx skills ls -a claude-code -a cursor +``` + +## `skills find` — Search for Skills + +```bash +npx skills find # Interactive search +npx skills find typescript # Search by keyword +npx skills find react --owner vercel +``` + +## `skills update` — Update Installed Skills + +```bash +npx skills update # All skills (interactive) +npx skills update my-skill # Single skill +npx skills update -g # Global only +npx skills update -y # Non-interactive +``` + +## `skills remove` (alias: `rm`) — Remove Installed Skills + +```bash +npx skills remove # Interactive +npx skills remove web-design-guidelines +npx skills remove --all # Remove everything +``` + +## `skills init` — Create a New SKILL.md Template + +```bash +npx skills init # In current directory +npx skills init my-skill # In a subdirectory +``` + +## `skills experimental_install` — Restore from Lock File + +```bash +npx skills experimental_install +``` + +## Aliases + +| Alias | Full Command | +|-------|-------------| +| `skills a` | `skills add` | +| `skills i` | `skills experimental_install` | +| `skills install` (no args) | `skills experimental_install` | +| `skills ls` | `skills list` | +| `skills rm` | `skills remove` | + +## Related + +* [Source Formats](/tools/vercel-labs-skills/source-formats.md) — What sources you can use with add/use +* [Installation Scope](/tools/vercel-labs-skills/installation-scope.md) — Global vs project diff --git a/omp-docs/tools/vercel-labs-skills/env-variables.md b/omp-docs/tools/vercel-labs-skills/env-variables.md new file mode 100644 index 0000000..9a0b5d9 --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/env-variables.md @@ -0,0 +1,33 @@ +--- +type: reference +title: Skills CLI Environment Variables +description: Environment variables — INSTALL_INTERNAL_SKILLS, DISABLE_TELEMETRY, DO_NOT_TRACK. +tags: + - unverified + - skills + - environment + - telemetry +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Environment Variables + +| Variable | Description | +|----------|-------------| +| `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` | +| `DISABLE_TELEMETRY` | Set to disable anonymous usage telemetry | +| `DO_NOT_TRACK` | Alternative way to disable telemetry | + +```bash +# Install internal skills +INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list +``` + +## Telemetry + +The CLI collects anonymous usage data to help improve the tool. No personal information is collected. Telemetry is automatically disabled in CI environments. + +## Related + +* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — `metadata.internal: true` diff --git a/omp-docs/tools/vercel-labs-skills/index.md b/omp-docs/tools/vercel-labs-skills/index.md new file mode 100644 index 0000000..844e147 --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/index.md @@ -0,0 +1,18 @@ +# Vercel Labs `skills` CLI + +Complete list of 68+ supported coding agents, their --agent flags, and installation paths (project and global). + +## Concept Files + +| File | Type | Description | +|------|------|-------------| +| [agent-support.md](agent-support.md) | reference | Complete list of 68+ supported coding agents, their --agent flags, and instal... | +| [commands.md](commands.md) | reference | Complete reference for all skills CLI commands — add, use, list, find, update... | +| [env-variables.md](env-variables.md) | reference | Environment variables — INSTALL_INTERNAL_SKILLS, DISABLE_TELEMETRY, DO_NOT_TR... | +| [installation-scope.md](installation-scope.md) | reference | Project vs global installation, symlink vs copy methods. | +| [lock-file.md](lock-file.md) | reference | Version pinning and update checking via global and local lock files (.skill-l... | +| [related-links.md](related-links.md) | reference | Links to the Agent Skills specification, skills directory, integration guide,... | +| [skill-discovery.md](skill-discovery.md) | reference | How the skills CLI discovers SKILL.md files in repositories — flat layout, ca... | +| [skill-format.md](skill-format.md) | reference | The required frontmatter fields, optional fields, internal skills, and struct... | +| [source-formats.md](source-formats.md) | reference | All accepted source formats for skills add and use — GitHub shorthand, full U... | + diff --git a/omp-docs/tools/vercel-labs-skills/installation-scope.md b/omp-docs/tools/vercel-labs-skills/installation-scope.md new file mode 100644 index 0000000..822b5ec --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/installation-scope.md @@ -0,0 +1,36 @@ +--- +type: reference +title: Skills CLI Installation Scope +description: Project vs global installation, symlink vs copy methods. +tags: + - unverified + - skills + - installation + - scope +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Installation Scope + +## Project vs Global + +| Scope | Flag | Location | Use Case | +|-------|------|----------|----------| +| **Project** | _(default)_ | `.//skills/` | Committed with your project, shared with team | +| **Global** | `-g` | `~//skills/` | Available across all projects | + +## Symlink vs Copy + +When installing interactively, you can choose: + +| Method | Description | +|--------|-------------| +| **Symlink** _(Recommended)_ | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. | +| **Copy** | Creates independent copies for each agent. Use when symlinks are not supported. | + +Use `--copy` to force copy mode. + +## Related + +* [Commands](/tools/vercel-labs-skills/commands.md) — add, use, list, remove commands diff --git a/omp-docs/tools/vercel-labs-skills/lock-file.md b/omp-docs/tools/vercel-labs-skills/lock-file.md new file mode 100644 index 0000000..f80c6cc --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/lock-file.md @@ -0,0 +1,43 @@ +--- +type: reference +title: Skills CLI Lock File System +description: Version pinning and update checking via global and local lock files (.skill-lock.json and skills-lock.json). +tags: + - unverified + - skills + - lockfile + - versioning +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Lock File System + +The `skills` CLI uses a lock file system for version pinning and update checking. + +## Lock File Locations + +| Type | Path | Scope | +|------|------|-------| +| **Global lock** | `~/.agents/.skill-lock.json` | Global (user-wide) | +| **Local lock** | `skills-lock.json` | Project (checked into version control) | + +## How `skills check` and `skills update` Work + +1. Read `~/.agents/.skill-lock.json` for installed skills +2. Filter to GitHub-backed skills that have both `skillFolderHash` and `skillPath` +3. For each skill, call `fetchSkillFolderHash(source, skillPath, token)` + - Optional auth token from `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token` +4. `fetchSkillFolderHash` calls GitHub Trees API (`/git/trees/?recursive=1` for `main`, then `master` fallback) +5. Compare latest folder tree SHA with lock file `skillFolderHash`; mismatch means update available +6. `skills update` reinstalls changed skills by invoking the current CLI directly + +## Lock File Format + +- **Version:** v3 +- **Key field:** `skillFolderHash` — GitHub tree SHA for the skill folder +- **Compatibility:** If reading an older lock file version, it is wiped. Users must reinstall skills to populate the new format. + +## Related + +* [Commands](/tools/vercel-labs-skills/commands.md) — check, update, experimental_install diff --git a/omp-docs/tools/vercel-labs-skills/related-links.md b/omp-docs/tools/vercel-labs-skills/related-links.md new file mode 100644 index 0000000..1ef2a34 --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/related-links.md @@ -0,0 +1,43 @@ +--- +type: reference +title: Vercel Labs Skills — Related Links +description: Links to the Agent Skills specification, skills directory, integration guide, and agent-specific skill documentation. +tags: + - unverified + - skills + - links + - resources +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Related Links + +## Specification & Ecosystem + +| Resource | URL | +|----------|-----| +| [Agent Skills Specification](https://agentskills.io) | agentskills.io/specification | +| [Skills Directory](https://skills.sh) | skills.sh | +| [Agent Skills Integration Guide](https://agentskills.io/integrate-skills) | agentskills.io/integrate-skills | +| [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills) | github.com/vercel-labs/agent-skills | + +## Agent-Specific Skill Documentation + +| Agent | Documentation | +|-------|--------------| +| Amp | [Amp Skills Documentation](https://ampcode.com/manual#agent-skills) | +| Claude Code | [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills) | +| Codex | [Codex Skills Documentation](https://developers.openai.com/codex/skills) (url unreachable 2026-08-28) | +| Cursor | [Cursor Skills Documentation](https://cursor.com/docs/context/skills) | +| Gemini CLI | [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/) (url unreachable 2026-08-28) | +| GitHub Copilot | [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) | +| OpenCode | [OpenCode Skills Documentation](https://opencode.ai/docs/skills) (url unreachable 2026-08-28) | +| OpenHands | [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills) (url unreachable 2026-08-28) | +| Pi | [Pi Skills Documentation](https://github.com/earendil-works/pi) | +| Roo Code | [Roo Code Skills Documentation](https://docs.roocode.com/features/skills) (url unreachable 2026-08-28) | +| Windsurf | [Windsurf](https://www.codeium.com/windsurf) (url unreachable 2026-08-28) | + +## Related + +* [Agent Support](/tools/vercel-labs-skills/agent-support.md) — Full list of 68+ supported agents diff --git a/omp-docs/tools/vercel-labs-skills/skill-discovery.md b/omp-docs/tools/vercel-labs-skills/skill-discovery.md new file mode 100644 index 0000000..fb4b3c8 --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/skill-discovery.md @@ -0,0 +1,63 @@ +--- +type: reference +title: Skills CLI Skill Discovery +description: How the skills CLI discovers SKILL.md files in repositories — flat layout, catalog layout, plugin manifests. +tags: + - unverified + - skills + - discovery + - repository +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Skill Discovery + +The CLI searches for skills in these locations within a repository. Each skill container directory is walked: + +- **One level deep** for the common flat layout: `skills//SKILL.md` +- **One extra level deep** for catalog layouts: `skills///SKILL.md` + +A `SKILL.md` discovered at the shallower level shadows anything nested below it. Use `--full-depth` to also discover `SKILL.md` files outside these container directories. + +## Standard Discovery Locations + +- `SKILL.md` in root directory (if present) +- `skills/` +- `skills/.curated/` +- `skills/.experimental/` +- `skills/.system/` +- `.agents/skills/` +- `.claude/skills/` +- `.goose/skills/` +- `.openhands/skills/` +- `.pi/skills/` +- And many more per-agent directories (see [Agent Support](/tools/vercel-labs-skills/agent-support.md)) + +## Plugin Manifest Discovery + +If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered. This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem. + +Example `marketplace.json`: + +```json +{ + "metadata": { "pluginRoot": "./plugins" }, + "plugins": [ + { + "name": "my-plugin", + "source": "my-plugin", + "skills": ["./skills/review", "./skills/test"] + } + ] +} +``` + +Skill paths declared in a manifest are searched at their declared depth. + +If no skills are found in standard locations, a **recursive search** is performed as a fallback. + +## Related + +* [SKILL.md Format](/tools/vercel-labs-skills/skill-format.md) — What a discovered skill looks like +* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands diff --git a/omp-docs/tools/vercel-labs-skills/skill-format.md b/omp-docs/tools/vercel-labs-skills/skill-format.md new file mode 100644 index 0000000..c04b896 --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/skill-format.md @@ -0,0 +1,70 @@ +--- +type: reference +title: SKILL.md Format +description: The required frontmatter fields, optional fields, internal skills, and structure for SKILL.md files. +tags: + - skills + - SKILL.md + - format + - unverified +verified: 2026-08-28 + +# SKILL.md Format + +Skills are directories containing a `SKILL.md` file with YAML frontmatter. + +## Basic Structure + +```markdown +--- +name: my-skill +description: What this skill does and when to use it +--- + +# My Skill + +Instructions for the agent to follow when this skill is activated. + +## When to Use + +Describe the scenarios where this skill is used. + +## Steps + +1. First, do this +2. Then, do that +``` + +## Required Frontmatter Fields + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Unique identifier (lowercase, hyphens allowed) | +| `description` | string | Brief explanation of what the skill does | + +## Optional Frontmatter Fields + +| Field | Type | Description | +|-------|------|-------------| +| `metadata.internal` | boolean | Set to `true` to hide the skill from normal discovery. Requires `INSTALL_INTERNAL_SKILLS=1` | +| `license` | string | License name or reference to bundled file | +| `compatibility` | string | Environment requirements (max 500 chars) | +| `metadata` | object | Arbitrary key-value mapping | +| `allowed-tools` | string | Space-delimited list of pre-approved tools (experimental) | +| `disable-model-invocation` | boolean | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly | + +## Internal Skills Example + +```markdown +--- +name: my-internal-skill +description: An internal skill not shown by default +metadata: + internal: true +--- +``` + +## Related + +* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are discovered in repos +* [Commands](/tools/vercel-labs-skills/commands.md) — `skills init` to create new skills diff --git a/omp-docs/tools/vercel-labs-skills/source-formats.md b/omp-docs/tools/vercel-labs-skills/source-formats.md new file mode 100644 index 0000000..18e320d --- /dev/null +++ b/omp-docs/tools/vercel-labs-skills/source-formats.md @@ -0,0 +1,43 @@ +--- +type: reference +title: Skills CLI Source Formats +description: All accepted source formats for skills add and use — GitHub shorthand, full URLs, GitLab, git URLs, local paths. +tags: + - unverified + - skills + - sources + - git +timestamp: 2026-07-18 +verified: 2026-08-28 +--- + +# Source Formats + +The `skills` CLI accepts multiple source formats for the `add` and `use` commands: + +```bash +# GitHub shorthand (owner/repo) +npx skills add vercel-labs/agent-skills + +# Full GitHub URL +npx skills add https://github.com/vercel-labs/agent-skills + +# Direct path to a skill in a repo +npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines + +# GitLab URL +npx skills add https://gitlab.com/org/repo + +# Any git URL +npx skills add git@github.com:vercel-labs/agent-skills.git + +# Local path +npx skills add ./my-local-skills +``` + +The source parser (`src/source-parser.ts`) handles all these formats, cloning repos as needed and resolving skill directories. + +## Related + +* [Commands](/tools/vercel-labs-skills/commands.md) — add and use commands +* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are found within repos