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.