Feature Request: Standardize .env Variable Namespaces Across PAI Packs

[madeinoz67]

Feature Request: Standardize .env Variable Namespaces Across PAI Packs

Summary

Propose a standardized naming convention for environment variables across PAI packs to prevent naming conflicts and improve clarity about which configuration belongs to which pack.

Problem Statement

As the PAI ecosystem grows with multiple packs (CORE, ART, OSINT, etc.), environment variable naming collisions are becoming a real risk. Currently, packs may use generic variable names that could conflict with each other or with system-level configuration.

Example Collision Scenario

Consider the existing PAI Art Pack (for logo and image generation using OpenAI's DALL-E) and a hypothetical future Writing Assistant Pack:

# Art Pack (existing) - .env
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini  # Used for DALL-E 3 prompts

# Writing Assistant Pack (hypothetical) - .env
OPENAI_API_KEY=sk-...  # Different key for OpenRouter perhaps?
OPENAI_MODEL=gpt-4o    # Different model for writing assistance

If both packs are active, which .env file takes precedence? How does the user configure different models or keys for each pack?

This problem compounds when:

• One pack uses OpenAI directly, another uses OpenRouter (which also requires OPENAI_API_KEY)
• Multiple packs need different model configurations for the same provider
• Packs have overlapping functional requirements (authentication, API endpoints, feature flags)

Proposed Solution

Adopt a two-tier namespace convention:

1. Official PAI Packs use PAI_<PACKNAME>_* prefix (reserved for danielmiessler/PAI ecosystem)
2. Third-Party Packs use <DEVELOPER>_<PACKNAME>_* prefix (based on GitHub repo/owner name)

Official PAI Packs (using PAI_*)

# Core PAI system
PAI_CORE_LOG_LEVEL=info
PAI_CORE_NOTIFICATIONS_ENABLED=true

# Art Pack (existing) - for logo and image generation
PAI_ART_OPENAI_API_KEY=sk-...
PAI_ART_OPENAI_MODEL=gpt-4o-mini

# Writing Assistant Pack (hypothetical official pack)
PAI_WRITING_OPENAI_API_KEY=sk-...
PAI_WRITING_OPENAI_MODEL=gpt-4o
PAI_WRITING_STYLE_GUIDE=professional

Third-Party / Community Packs (using developer prefix)

# madeinoz-knowledge-system (third-party pack)
MADEINOZ_KNOWLEDGE_OPENAI_API_KEY=sk-...
MADEINOZ_KNOWLEDGE_DB_BACKEND=neo4j
MADEINOZ_KNOWLEDGE_GRAPHITI_MODEL=gpt-4o

# johndoe-devtools (hypothetical third-party pack)
JOHNDOE_DEVTOOLS_API_ENDPOINT=...
JOHNDOE_DEVTOOLS_DEBUG_MODE=true

# acme-corp-pentesting (hypothetical third-party pack)
ACME_CORP_PENTESTING_TARGET_SCOPE=...
ACME_CORP_PENTESTING_REPORT_FORMAT=json

Benefits

1. Collision Prevention: Each pack has its own namespace, eliminating conflicts
2. Clear Attribution: Variable names immediately identify which pack they belong to
3. Official vs Third-Party Distinction: PAI_* prefix signals official packs; developer prefixes signal community packs
4. Owner Identification: Third-party prefixes immediately identify the developer/maintainer
5. Better IDE Experience: Autocomplete shows grouped variables by pack
6. Easier Debugging: Logs can reference PAI_ART_* or MADEINOZ_KNOWLEDGE_* variables unambiguously
7. Migration Path: Existing variables can be gradually deprecated with aliases
8. Documentation Clarity: Each pack's .env.example is self-documenting

Implementation Plan

1. Define Two-Tier Prefix System (in PAI CORE)

   • Reserve PAI_* namespace for official danielmiessler/PAI ecosystem packs only
   • Document third-party prefix convention: use GitHub repo/owner name (uppercase, hyphens to underscores)
   • Examples: MADEINOZ_*, JOHNDOE_*, ACME_CORP_*
   • Add official prefix request process for new core packs

2. Update Official PAI Packs

   • Rename environment variables with PAI_<PACK>_* prefix
   • Support old variable names as deprecated aliases with migration warnings
   • Update .env.example files
   • Update documentation

3. Third-Party Pack Guidelines

   • Document prefix convention in pack development guide
   • Provide examples and best practices
   • Optional: Add validation hook to suggest developer prefix for PAI_* usage in non-official repos

4. Migration Timeline

   • Phase 1: New variables supported, old variables deprecated with warnings
   • Phase 2: Old variables emit errors (after 6-month grace period)
   • Phase 3: Remove alias support

Open Questions

1. How should third-party prefixes handle collisions? (e.g., two developers named "JOHNDOE")

   • Recommendation: Document conflict resolution (e.g., use GitHub username JOHNDOE_GITHUB_* vs JOHNDOE_BITBUCKET_*) — rare in practice

2. Should there be a "shared" namespace for commonly used config? (e.g., PAI_SHARED_OPENAI_KEY)

   • Recommendation: No — explicit is better than implicit, packs should document their requirements

3. How to handle secrets management? Should packs define their own secret structure?

   • Recommendation: Yes, pack-prefixed secrets are more secure and auditable

4. Should this be enforced via tooling or convention?

   • Recommendation: Convention first (documentation), tooling later (validation hooks)

Alternatives Considered

• Hierarchical config files: More complex, harder to use with existing tools
• Central config registry: Single point of failure, harder to extend
• No standardization: Status quo — will cause problems as ecosystem grows