From 7a0b435923241ffe2c19f7b128bcb86b328665b2 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Mon, 26 Jan 2026 12:38:04 +0100
Subject: [PATCH] docs(coding-agent): add security warnings for third-party
 packages

- README.md: Pi Packages section
- packages.md: Install and Manage section
- extensions.md: Extension Locations section
- skills.md: Locations section
---
 packages/coding-agent/README.md          | 2 ++
 packages/coding-agent/docs/extensions.md | 2 ++
 packages/coding-agent/docs/packages.md   | 7 ++++++-
 packages/coding-agent/docs/skills.md     | 4 +++-
 4 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index 6e074a5b..db9c4b9a 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -319,6 +319,8 @@ Place in `~/.pi/agent/themes/`, `.pi/themes/`, or a [pi package](#pi-packages) t
 
 Bundle and share extensions, skills, prompts, and themes via npm or git. Find packages on [npmjs.com](https://www.npmjs.com/search?q=keywords%3Api-package) or [Discord](https://discord.com/channels/1456806362351669492/1457744485428629628).
 
+> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
+
 ```bash
 pi install npm:@foo/pi-tools
 pi install npm:@foo/pi-tools@1.2.3      # pinned version
diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/docs/extensions.md
index f2830339..53de0117 100644
--- a/packages/coding-agent/docs/extensions.md
+++ b/packages/coding-agent/docs/extensions.md
@@ -103,6 +103,8 @@ pi -e ./my-extension.ts
 
 ## Extension Locations
 
+> **Security:** Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.
+
 Extensions are auto-discovered from:
 
 | Location | Scope |
diff --git a/packages/coding-agent/docs/packages.md b/packages/coding-agent/docs/packages.md
index ad6e7f71..69aa2cc7 100644
--- a/packages/coding-agent/docs/packages.md
+++ b/packages/coding-agent/docs/packages.md
@@ -16,6 +16,8 @@ Pi packages bundle extensions, skills, prompt templates, and themes so you can s
 
 ## Install and Manage
 
+> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
+
 ```bash
 pi install npm:@foo/bar@1.0.0
 pi install git:github.com/user/repo@v1
@@ -139,10 +141,13 @@ Filter what a package loads using the object form in settings:
 }
 ```
 
+`+path` and `-path` are exact paths relative to the package root.
+
 - Omit a key to load all of that type.
 - Use `[]` to load none of that type.
 - `!pattern` excludes matches.
-- `+pattern` force-includes, even if excluded by manifest.
+- `+path` force-includes an exact path.
+- `-path` force-excludes an exact path.
 - Filters layer on top of the manifest. They narrow down what is already allowed.
 
 ## Enable and Disable Resources
diff --git a/packages/coding-agent/docs/skills.md b/packages/coding-agent/docs/skills.md
index f8230cad..588d5fc1 100644
--- a/packages/coding-agent/docs/skills.md
+++ b/packages/coding-agent/docs/skills.md
@@ -19,6 +19,8 @@ Pi implements the [Agent Skills standard](https://agentskills.io/specification),
 
 ## Locations
 
+> **Security:** Skills can instruct the model to perform any action and may include executable code the model invokes. Review skill content before use.
+
 Pi loads skills from:
 
 - Global: `~/.pi/agent/skills/`
@@ -50,7 +52,7 @@ For project-level Claude Code skills, add to `.pi/settings.json`:
 
 ```json
 {
-  "skills": [".claude/skills"]
+  "skills": ["../.claude/skills"]
 }
 ```