[ardiloot]

This pull request significantly expands and clarifies the documentation for pubgate, focusing on the new preview command, improved auxiliary directory handling, stricter public publishing requirements, and more detailed CLI and configuration references. The updates make the workflows, options, and edge cases much clearer, and introduce new features for local testing and auxiliary content management.

Major documentation improvements and new features:

New Features and Workflow Enhancements

• Added a new preview command that allows users to generate a local-only filtered worktree from any clean local commit for testing, without requiring a merge to main or interaction with the public repo. This is now documented in both the workflow and CLI reference sections. [1] [2] [3] [4]
• Introduced support for mapping external auxiliary directories into the reviewed snapshot, with configuration, filtering, and lifecycle clearly documented. [1] [2]

CLI Reference and Option Clarifications

• Expanded the CLI reference to include all commands and options, with clear separation of global and per-command flags, and detailed requirements for the new publish workflow (explicit author name/email/message). [1] [2]
• Clarified worktree and branch requirements for each command, especially around clean state, branch sync, and handling of unpushed commits. [1] [2]

Edge Cases and Error Handling

• Documented new edge cases and error messages for preview, auxiliary directory management, and Git LFS handling, including how preview interacts with LFS and what happens if auxiliary sources are missing. [1] [2]
• Updated error table with new preview-specific errors and clarified existing error messages.

Security and Public Release Process

• Made it explicit that publish now requires a public author identity and commit message, never leaking internal metadata or using internal signing keys. [1] [2] [3]
• Clarified how commit messages are handled for absorb, stage, and publish steps to prevent information leaks.

Internal Consistency and Spec Updates

• Updated the specification to reflect the new preview command, auxiliary directory digest handling, and startup sequences for all commands. [1] [2]

These changes provide much clearer guidance for both new and existing users, and introduce important new capabilities for local testing and auxiliary data management.