Provide .gitignore for user installs + manifest of PAI-managed files

[renoirb]

Problem

Users who git init . in their ~/.claude (or PAI install directory) have no clear way to know which files are PAI-managed vs their own customizations. This
makes it difficult to:

• Version control personal configurations without tracking upstream files
• Know what's safe to modify vs what may be overwritten on upgrade
• Maintain a clean separation between PAI core and user content

Proposal

1. PAI-managed manifest - PAI declares which files/paths it maintains
2. Install .gitignore - Ships with the install (not source repo) so users can git init . and immediately have sensible ignores for PAI-managed paths

Example .gitignore at install location:

# PAI-managed - excluded from user versioning
skills/CORE/SYSTEM/
skills/Browser/
lib/
tools/
hooks/SessionStart.ts
# ... etc

Enhancement: TOML companion for tooling

A .gitignore solves the git use case, but tooling (upgrade scripts, integrity checks, conflict detection) benefits from programmatic parsing. Consider a
companion:

# pai-managed.toml
[managed]
paths = [
  "skills/CORE/SYSTEM/**",
  "lib/**",
  "tools/**"
]

Same patterns, machine-readable. The .gitignore remains the human-facing artifact; TOML enables automation without regex parsing.

[renoirb]

At the moment, here's the $PAI_DIR/.gitignore I am using.

# ~/.claude/.gitignore
# Personal AI Infrastructure (PAI) - Git Ignore Rules
#
# This file defines what should be tracked vs ignored in your PAI installation.
# Track: configuration, skills, hooks, and infrastructure code
# Ignore: runtime state, caches, logs, and secrets

# =============================================================================
# SECRETS & CREDENTIALS (NEVER COMMIT)
# =============================================================================
.env
.env.*
*.pem
*.key
*.cert
*.p12
*.pfx
*_rsa
*_rsa.pub
*.crt
*.cer

# =============================================================================
# RUNTIME STATE & SESSION DATA
# =============================================================================
# Session tracking
.current-session
agent-sessions.json
history.jsonl

# Per-session environments
session-env/

# Shell state
shell-snapshots/

# Statistics & analytics
stats-cache.json
statsig/

# Todos (per-session state)
todos/

# Projects (project-specific runtime data)
projects/

# Agents (agent runtime state)
agents/

# IDE state
ide/

# Plans (temporary planning)
plans/

# =============================================================================
# LOGS & DEBUG OUTPUT
# =============================================================================
debug/
*.log
logs/

# File operation history
file-history/

# Telemetry
telemetry/

# =============================================================================
# CACHE & TEMPORARY FILES
# =============================================================================
cache/
.cache/
*.cache
*.tmp
tmp/
temp/

# =============================================================================
# MEMORY SYSTEM (Selective Tracking) - PAI v7.0+
# =============================================================================
# The MEMORY system distinguishes between:
# - PERMANENT: Research, learnings, synthesis, system updates → TRACKED
# - OPERATIONAL: State, signals, security logs → IGNORED (listed below)
#
# Reference: MEMORYSYSTEM.md in pai-core-install pack
# Strategy: Ignore operational/ephemeral dirs; track curated knowledge

# ---- OPERATIONAL STATE (Ignore - ephemeral, can be rebuilt) ----
# Per MEMORYSYSTEM.md: "Ephemeral - can be rebuilt... If deleted, system recovers gracefully"
MEMORY/STATE/

# ---- SECURITY LOGS (Ignore - rolling audit trail) ----
MEMORY/SECURITY/

# ---- RAW SIGNALS (Ignore - aggregated into LEARNING/SYNTHESIS/) ----
MEMORY/LEARNING/SIGNALS/

# ---- PERMANENT MEMORY (Tracked - not ignored) ----
# These are tracked automatically because they're not in this ignore list:
#   ✅ MEMORY/WORK/                - Primary work tracking (valuable work artifacts)
#   ✅ MEMORY/LEARNING/SYSTEM/     - PAI/tooling learnings (curated)
#   ✅ MEMORY/LEARNING/ALGORITHM/  - Task execution learnings (curated)
#   ✅ MEMORY/LEARNING/SYNTHESIS/  - Aggregated pattern reports
#   ✅ MEMORY/RESEARCH/            - Agent output captures
#   ✅ MEMORY/PAISYSTEMUPDATES/    - Architecture change history
#   ✅ MEMORY/README.md            - Documentation

# =============================================================================
# HISTORY SYSTEM (Legacy - might be symlink to MEMORY)
# =============================================================================
history/

# =============================================================================
# PLUGINS & EXTERNAL DEPENDENCIES
# =============================================================================
plugins/

# Node/Bun dependencies (if any get installed here)
node_modules/
.npm
.yarn

# =============================================================================
# macOS ARTIFACTS
# =============================================================================
.DS_Store
.AppleDouble
.LSOverride
Icon
._*
.Spotlight-V100
.Trashes

# =============================================================================
# BUILD OUTPUTS (if any tools generate them)
# =============================================================================
dist/
build/
out/

# =============================================================================
# YOUR FILES (User-owned - PAI updates will never overwrite these)
# =============================================================================
# These paths belong to you. Explicitly tracked with negation patterns.
# Add your custom skills/agents to this section as you create them.

# Your configuration
!settings.json
!CLAUDE.md

# Your personal context (the USER tier - always yours)
!skills/CORE/USER/

# Your private skills (underscore prefix convention)
!skills/_*/

# Your custom skills (add your skill paths below)
!skills/PortfolioAnalysis/

# =============================================================================
# PAI FILES (PAI-provided - may be updated with new versions)
# =============================================================================
# These come from PAI packs. Updates may modify them.
# If you customize these, consider copying to USER tier or _PREFIX skill.
#
# PAI-provided (tracked, but owned by PAI):
#   skills/Agents/
#   skills/Art/
#   skills/Browser/
#   skills/CORE/SYSTEM/
#   hooks/
#   agents/
#   tools/

# =============================================================================
# TRACKED BY DEFAULT (not ignored above)
# =============================================================================
# ✅ hooks/              - Event-driven automation scripts
# ✅ skills/             - Skill definitions and workflows
# ✅ tools/              - Utility scripts and tools
# ✅ agents/             - Agent definitions
# ✅ MEMORY/WORK/        - Primary work tracking with verification artifacts
# ✅ MEMORY/LEARNING/    - Curated learnings (except SIGNALS/)
# ✅ MEMORY/RESEARCH/    - Agent output captures
# ✅ MEMORY/PAISYSTEMUPDATES/ - Architecture change history
# ✅ VoiceServer/        - Voice system (if non-secret)

# =============================================================================
# NOTES
# =============================================================================
# - Always review `settings.json` before committing - it may contain paths
#   or identifiers you want to sanitize
# - The MEMORY rules above track curated knowledge but ignore operational data
# - Adjust MEMORY/LEARNING/SIGNALS/ if you want to track raw rating signals
# - This .gitignore assumes ~/.claude is its own git repository

[wojteksbt]

@renoirb do you actively use this .gitignore and does it work as expected (syncing all important memory and not messing anything else)? I created my own synchronization setup, but it messes up with hooks and who knows what else, so I'm willing to test yours.

[danielmiessler]

Thanks for this feedback! We're currently working on PAI v3.0, which includes significant architectural changes. We're evaluating this issue in the context of the new architecture and will provide an update once v3.0 is closer to release.

Please stand by — we haven't forgotten about this and appreciate your contribution to making PAI better!

[kaimagnus]

Thanks for this proposal! The .gitignore part has been addressed — we've added a .gitignore to the release's .claude/ directory (commit 20f1b39, via #578) that covers all standard Claude Code runtime folders.

The manifest/TOML idea for tracking PAI-managed vs user files is interesting for the future, but v3.0's architecture handles this differently:

• USER tier files (_ALLCAPS skills, USER/ directory) are clearly separated from system files
• `settings.json` is the hybrid config that preserves user values across updates
• The installer handles the upgrade path

The immediate need (.gitignore for user installs) is resolved. The PAI-managed manifest concept is a good future enhancement but doesn't have an immediate path in the current architecture. Closing as the primary ask is addressed.