star-chart-search-enhancer/docs/superpowers/specs/2026-05-25-unified-dist-distribution-design.md

Unified Dist Distribution Design

Goal

Make first-time installation and later updates use the exact same extension directory structure so coworkers never need to learn different paths or loading rules.

Confirmed Direction

• The only user-facing unpacked extension directory should be dist/.
• First install and later update must produce the same directory name and shape.
• Coworkers should always load the same directory in chrome://extensions.

Problem

The current delivery flow has created multiple mental models:

• sometimes coworkers are told to load dist-release/
• sometimes the ZIP extracts to a differently named top-level folder
• sometimes Git-based installation and ZIP-based installation do not look identical

This is not user-friendly and increases support cost.

Scope

This change standardizes the user-facing extension directory across:

• local release builds
• ZIP packaging
• Git-based teammate installation
• later update downloads
• installation and update documentation

This change does not alter:

• extension runtime behavior
• update-check logic itself
• popup auth flow
• COS manifest format

Distribution Rule

There must be exactly one user-facing extension directory:

• dist/

This rule must hold in all paths:

1. Git install
   • teammate runs the release build
   • resulting unpacked extension directory is dist/
2. ZIP install
   • teammate unzips the package
   • resulting top-level extension directory is dist/
3. ZIP update
   • teammate downloads the newer ZIP
   • unzip result is also dist/
   • teammate replaces the previous dist/

Packaging Rule

The release ZIP should unpack into a single top-level folder named dist/.

Expected unpack result:

• dist/manifest.json
• dist/background/
• dist/content/
• dist/popup/
• dist/assets/

The ZIP must not unpack as:

• a flat file list
• dist-release/
• star-chart-search-enhancer-internal/
• any other user-facing top-level folder name

Build Rule

Release builds should write the unpacked extension directly to dist/.

There should not be a second extension build directory that teammates might mistake as the correct one.

If internal scripts need a concept of “release build,” that should be represented by:

• environment/config
• release manifest values
• packaging flow

but not by exposing a second unpacked directory name to users.

Documentation Rule

All teammate-facing docs must say the same thing:

• first install: load dist/
• later update: replace dist/ and reload

No user-facing doc should mention dist-release/.

CI / Release Rule

Drone and local release scripts must publish only one ZIP layout:

• unzip result is dist/

The release flow must not generate a user ZIP whose folder layout differs from the Git-based install path.

Acceptance Criteria

• npm run build:release writes the unpacked extension to dist/
• release ZIP unpacks into a top-level dist/ folder
• first install and later update ZIPs unpack to the same structure
• coworker docs consistently reference dist/
• repository no longer contains a second tracked unpacked extension directory that conflicts with dist/

Out of Scope

• changing extension features
• changing the update notification UX
• switching away from unpacked-extension installation
• Chrome Web Store or enterprise force-install deployment