# Best practices for working with Paver

Use these best practices across your day-to-day work, initial setup, and advanced workflows to keep your environment secure, fast, and predictable. Getting the most out of IBM® Paver comes down to leaning into its operator model. Paver runs in your infrastructure and runs governed operations through your existing command-line interface (CLI), API, and platform tooling.

## Daily usage best practices

Use precise context triggers, clear guardrails, and persistent memory to speed up your everyday workflows.

### Supply instant context with @ mentions

Instead of copying and pasting multi-megabyte log files or large configuration manifests into the prompt, use the `@` trigger to give Paver targeted context:

- **Local files**: Type `@/path/to/file.tf` to upload the file to your workspace and attach it to the prompt.
- **Cloud resources**: Type `@my-vpc-prod` to have Paver pull and attach the live resource metadata.
- **Workspace files**: Type `@logs.txt` to reference a file that is already in your persistent workspace.

### Choose the right mode and guardrails for the job

Control how much execution permission Paver has during a session:

- **Safe mode (`/safe`)**: Use this for discovery, audits, troubleshooting, and planning. Paver can't make changes in your environment, but it can read and write files in the sandbox, such as scripts or Terraform for your plan.
- **Edit mode (`/edit`)**: Use this mode when you are ready to make changes with policy-based human approvals.
- **Speed up routine low-risk actions**: If you find yourself approving routine read or list operations too often, raise the auto-approval threshold:
  ```text
  /guard auto-approve-low
  ```

### Plan before you ask Paver to do the work

For any task that has more than a few steps, ask Paver for a written plan before you ask it to make changes. A plan gives you a chance to correct misunderstandings while they are still easy to fix.

1. **Switch to safe mode and request a plan**: In safe mode, Paver can't make changes in your environment, but it can write files in the sandbox. Ask for concrete, ordered steps, and ask Paver to save the plan as a file:
   ```text
   Create a plan in plan.md for migrating the staging cluster to the new VPC. List each step, the commands or tools that you will use, the resources that are affected, and how to verify each step.
   ```
2. **Review the plan**: Check that Paver understood your goals, constraints, and environment. Look for missing steps, wrong assumptions, and steps that affect resources that you didn't intend.
3. **Refine the plan**: Ask Paver to update the document until it matches what you want. You can attach the file to a prompt with `@plan.md`.
4. **Run the plan**: When you're satisfied, switch to edit mode with `/edit` and ask Paver to complete the plan. Policy-based approvals still apply to each change.

### Use subagents for research tasks

When a task involves researching or gathering information, such as comparing configurations across several accounts or reviewing many resources, suggest that Paver use subagents. A subagent works on a focused part of the task in its own context and reports a summary back. Subagents can make research faster and reduce the number of tokens that Paver uses, which helps you stay within your usage quota.

```text
Use subagents to research the configuration of my development, staging, and production environments in parallel, then summarize the differences in one table.
```

Subagents work best for self-contained research. For small lookups or tasks where each step depends on the previous one, Paver can usually do the work directly.

### Put memory to work

Paver stores your operational preferences across conversations so that you don't have to repeat them.

- **Seed your environment defaults**: Tell Paver your project context once in natural language:
  ```text
  paver ask "Note that I work on Project Apollo and my default region is us-south"
  ```
- **Review and clean up memory**: Run `/memory` to see what Paver has stored about your setup. If you switch to a new project or account, clear outdated entries:
  ```text
  /memory clear
  ```

## Setup best practices

Configure credential handling and sandbox connectivity first so that you can run tasks without interruption.

### Use the keyring for secrets

Do not pass API keys, tokens, or passwords directly in your prompts. Prompts stay in conversation history, but the encrypted keyring injects exported secrets directly into the sandbox as environment variables when commands run.

- **Set a time-to-live (TTL) on temporary keys**: Give sensitive tokens an expiration so that they are removed automatically:
  ```text
  paver keyring add MY_TOKEN --ttl 7d
  ```

- **Automatically export keys that you use every day**: Avoid running `/keyring export` every time you open a session. Add frequently used keys to the `autoExport` array in `~/.paver/config.json`, and Paver makes them available when your sandbox starts:

  ```text
  {
  "keyring": {
    "autoExport": [
      "ibmcloud_api_key",
      { "key": "github_token", "as": "GITHUB_TOKEN" }
    ]
  }
  }
  ```

- **Keep secrets at eight characters or more**: The Paver automatic redaction engine masks strings in the chat only if they are at least eight characters long.

### Set up a custom shell host for your sandbox

Paver runs commands inside an isolated sandbox.

- **Connect to private subnets without tunneling**: By default, Paver uses a public sandbox. If you need to manage resources in a private VPC or corporate intranet, do not try to build tunnels through the public sandbox. Instead, register a Linux host inside that network as a custom shell:
  ```text
  paver shell register <name>
  ```
- **Use preinstalled tools**: Standard tools such as `ibmcloud`, `kubectl`, `terraform`, and `oc` are already installed in the sandbox. Paver calls them directly during execution, or you can open the interactive shell yourself:
  ```text
  /shell
  ```

## Advanced best practices

Automate recurring runbooks and keep project assets ready across sessions.

### Build custom skills for repeatable workflows

If you find yourself giving Paver the same five-step instructions every week, turn the procedure into a skill:

- **Upload your team's domain logic**: Package your team's knowledge into a folder and upload it:
  ```text
  paver skills upload ./my-skill/
  ```
- **Trigger skills on demand**: Set `user-invokable: true` in the skill front matter so you can run it as a custom slash command (such as `/my-custom-cleanup`).

### Treat your workspace as a project folder

Use `~/.paver/files/` as your persistent project folder. Upload your Terraform modules, shell scripts, and configuration bundles once, and they stay available across all future sessions without repeated uploads.