Add user-focused permissions documentation under "Using Wassette"

[Copilot]

• Analyze current permission system documentation structure
• Create new user-focused "Using Wassette" section directory structure
• Create new docs/using/permissions.md with user-focused how-to content
• Update docs/SUMMARY.md to add "Using Wassette" section with permissions page
• Build and verify documentation with mdbook
• Review content for consistency and clarity
• Update CHANGELOG with documentation changes
• Reorder "Granting Permissions" section to prioritize MCP built-in tools
• Add environment variable visibility note
• Add policy file management clarification
• Final review and validation

Summary

This PR addresses the issue about improving the permissions documentation by creating a new user-focused "Permissions" page under a "Using Wassette" section.

Changes Made

1. New Documentation Structure: Created docs/using/ directory for user-focused guides
2. User-Focused Permissions Guide: Created comprehensive docs/using/permissions.md with practical how-to content
3. Updated Documentation Index: Modified docs/SUMMARY.md to add "Using Wassette" section
4. CHANGELOG Update: Documented the new permissions documentation
5. Prioritized MCP Built-in Tools: Reordered to recommend using AI agents first
6. Added Important Notes:
   • Environment variable visibility requirement (wassette secret set or env vars)
   • Policy files are typically auto-managed by Wassette tools

Key Improvements

• MCP-First Approach: The recommended approach is now to use MCP built-in tools through natural language with AI agents
• Clear Prioritization:
  1. Using MCP Built-in Tools (Recommended) - Natural language permission requests
  2. Using CLI Commands - For direct management and scripting
  3. Using Policy Files - Auto-managed by Wassette, not typically manual
• Environment variable note explains how to provide env vars to the server
• Policy files section clarifies these are managed by Wassette automatically
• User-centric focus on practical tasks
• Clear examples for all three approaches
• Security best practices with good/bad examples
• Complete troubleshooting guide

The permissions documentation is now clearly separated:

• User Docs (docs/using/permissions.md): Practical how-to guide
• Design Docs (docs/design/permission-system.md): Technical architecture details

Screenshots

Environment Variable Note:

Policy Files Clarification:

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Docs: The permission system doc needs some work</issue_title>
<issue_description>It currently reads like a design document, instead of user-side docs.

We should add a new “Permissions” under “Using Wassette.” The user page should avoid internals and focus on tasks and provides How-to topics:. </issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #332

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Mossaka]

@copilot

[Mossaka]

the policy file is not a recommended way for granting. You should modify it to use built-in tools and the agent will figure out how to grant permissions. The CLI experience is secondary to that.

[Copilot]

Reordered the "Granting Permissions" section to prioritize MCP built-in tools as the recommended approach. The section now leads with using the AI agent through natural language, followed by CLI commands, then policy files. Added clear "(Recommended)" label and explanation that policy files are secondary to agent-based permission granting.

Changes in commit 004006a3.

[Mossaka]

@copilot added more comments

[Mossaka]

Add a note that the even after the env var permissions are granted, the server still needs to be able to see those env vars.

One way of doind that is to run wassette secret set to inject secrets into this. Another way is to run the server with the necessasry env vars

[Copilot]

Added a note after the environment variable permissions section explaining that the server must be able to see those environment variables. The note provides two methods: using wassette secret set <component-id> <key> <value> to inject secrets, or running the server with the necessary environment variables already set.

Changes in commit [SHA will be added after commit].

[Mossaka]

Note that this is not meant to be manually write. It's a file that wassette can manipulate using the grant-* built in tools or CLI.

[Copilot]

Updated the "Using Policy Files" section to clarify that policy files are typically managed automatically by Wassette when using the built-in tools or CLI commands, rather than being manually written. The section now states: "Policy files store permissions for components in YAML format. These files are typically managed automatically by Wassette when you use the built-in tools or CLI commands rather than being manually written."

Changes in commit [SHA will be added after commit].