docs: improve Spark developer onboarding

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,70 @@
+name: Bug report
+description: Report a reproducible Spark theme issue.
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a Spark issue. Do not include API keys, customer data, merchant credentials, or exploit details.
+  - type: input
+    id: version
+    attributes:
+      label: Spark version or commit
+      description: Use the README version, Git tag, or commit SHA.
+      placeholder: "1.1.1 or add24e9"
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Include the smallest safe reproduction you can share.
+      placeholder: |
+        1. Clone Spark at ...
+        2. Configure ...
+        3. Run ...
+        4. See ...
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Affected surface
+      options:
+        - Theme Settings
+        - Homepage section partial
+        - Product detail page
+        - Cart or side cart
+        - Web Component
+        - App hook
+        - CSS build or compatibility
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: checks
+    attributes:
+      label: Verification
+      description: Paste relevant local command output.
+      placeholder: |
+        python3 -m unittest discover -s tests
+        python3 scripts/sass-compat.py --check assets/main.css
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Store-specific support
+    url: https://github.com/NextCommerceCo/spark/blob/main/CONTRIBUTING.md#public-issues-and-support
+    about: Use your normal Next Commerce support channel for merchant-specific store issues.
+  - name: Security reports
+    url: https://github.com/NextCommerceCo/spark/security/advisories/new
+    about: Report vulnerabilities privately. Do not open public issues with exploit details or secrets.

.github/ISSUE_TEMPLATE/dx_feedback.yml

@@ -0,0 +1,49 @@
+name: Developer experience feedback
+description: Share friction from installing, extending, debugging, or contributing to Spark.
+title: "[DX]: "
+labels:
+  - dx
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for onboarding friction, unclear docs, confusing errors, missing examples, or extension pain. Do not include secrets or merchant-specific private data.
+  - type: dropdown
+    id: journey_stage
+    attributes:
+      label: Journey stage
+      options:
+        - Discover
+        - Install
+        - Local verification
+        - Store install
+        - Extending the theme
+        - Debugging
+        - Upgrade or release
+        - Contributing
+    validations:
+      required: true
+  - type: textarea
+    id: attempted
+    attributes:
+      label: What were you trying to do?
+      description: Describe your goal and the docs, commands, or files you used.
+    validations:
+      required: true
+  - type: textarea
+    id: friction
+    attributes:
+      label: Where did you lose time?
+      description: Include confusing copy, missing next steps, unclear errors, or decisions the docs forced you to guess.
+    validations:
+      required: true
+  - type: textarea
+    id: better
+    attributes:
+      label: What would have helped?
+      description: A command, example, screenshot, doc page, warning, or default behavior.
+  - type: input
+    id: time_lost
+    attributes:
+      label: Time lost
+      placeholder: "e.g., about 10 minutes"

.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Verify theme tooling
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install CI dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pyyaml
+
+      - name: Validate GitHub YAML
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          import yaml
+
+          for path in sorted(Path(".github").glob("**/*.yml")):
+              with path.open() as handle:
+                  yaml.safe_load(handle)
+              print(f"OK: {path}")
+          PY
+
+      - name: Run tests
+        run: python -m unittest discover -s tests
+
+      - name: Run JavaScript module tests
+        run: |
+          for test_file in tests/js/*.test.js; do
+            node "$test_file"
+          done
+
+      - name: Check committed CSS compatibility
+        run: python scripts/sass-compat.py --check assets/main.css

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable public Spark changes should be recorded here.
+
+Spark follows human-readable release notes rather than a strict package-manager version contract. The current public version is shown in [README.md](README.md). When releasing a new version, update the README version, add a dated changelog section, and publish a Git tag or GitHub release when the repo is ready for external consumers to pin versions.
+
+## 1.1.2 - Unreleased
+
+- Clarified the first-run path for local inspection versus installing Spark on a real Next Commerce store.
+- Added contribution guidance, issue templates, CI checks, and an extension guide for theme developers.
+
+## 1.1.1 - 2026-06-17
+
+- Added metadata-driven membership pricing presentation for product cards, PDP surfaces, and sticky add-to-cart pricing.
+- Refreshed public-facing docs around components, app hooks, and public readiness.
+
+## 1.1.0 - 2026-04-28
+
+- Expanded homepage section partials and Theme Settings coverage.
+- Documented the Figma section library path, performance load order, cart events, PDP variant state, and theme settings partials.
+- Committed compiled `assets/main.css` so Spark can be installed without a local Tailwind build.
+
+## 1.0.0 - 2026-03-20
+
+- Initial public Spark starter theme for Next Commerce.
+- Introduced Tailwind CSS v4, vanilla JavaScript, Web Components, committed storefront templates, and zero jQuery or Bootstrap dependency.

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing To Spark
+
+Spark is a public starter theme for Next Commerce storefronts. Contributions should keep the theme easy to inspect, install, customize, and safely extend.
+
+## Before You Start
+
+- Read [README.md](README.md) for the current setup and verification commands.
+- Read [DESIGN.md](DESIGN.md) before changing storefront UI.
+- Read [docs/extending-spark.md](docs/extending-spark.md) before adding settings, partials, app hooks, or Web Components.
+- Keep `config.yml`, API keys, store domains, merchant data, and local tool state out of commits.
+
+## Local Verification
+
+Run the checks that match your change:
+
+```bash
+python3 -m unittest discover -s tests
+python3 scripts/sass-compat.py --check assets/main.css
+```
+
+The standard local checks do not need extra Python packages. CI also validates GitHub workflow and issue-template YAML with PyYAML; install `pyyaml` first if you run that optional check locally.
+
+If you change `css/input.css`, rebuild and check the generated CSS:
+
+```bash
+make css-check
+```
+
+If you do not already have the Tailwind standalone binary, install it first:
+
+```bash
+make install-tailwind
+```
+
+When a CSS source change is ready to commit, run:
+
+```bash
+make release
+```
+
+That rebuilds and stages `assets/main.css`. Commit the source CSS and generated CSS together.
+
+## Pull Request Checklist
+
+- Explain the user-facing or theme-developer impact.
+- Name the relevant [PLAN.md](PLAN.md) workstream when it applies; otherwise explain the public DX or user impact in plain language.
+- Include screenshots for storefront UI changes at desktop and mobile widths.
+- Include the exact commands you ran and their results.
+- Update docs when behavior, settings, events, public APIs, or release steps change.
+- Keep pull requests focused. Separate docs polish, platform behavior, and storefront UI when they can land independently.
+
+## Public Issues And Support
+
+Use the GitHub issue templates for reproducible bugs and developer-experience feedback. Include reproduction steps, expected behavior, actual behavior, and the Spark version or commit. If issue creation is unavailable for your account or the topic is store-specific, use your normal Next Commerce support channel.
+
+For security reports, do not open a public issue. Follow [SECURITY.md](SECURITY.md).
+
+For store-specific support, use your normal Next Commerce support channel and never post API keys, customer data, merchant configuration, or exploit details publicly.
+
+## Branching
+
+NextCommerceCo repositories use branch and pull request flow. Do not push directly to `main`. Keep generated artifacts such as `assets/main.css` in the same pull request as the source change that produced them.

PLAN.md

@@ -108,7 +108,7 @@ Spark should be ready if NEXT adds platform-level theme sections, but current Sp
 The public repository should stay easy for theme developers to understand, audit, and extend.
 
 - Keep `README.md`, `CLAUDE.md`, `PLAN.md`, and `docs/` accurate as Spark evolves.
-- Add an "Extending Spark" guide for settings, partials, app hooks, and Web Components.
+- Keep the "Extending Spark" guide current as settings, partials, app hooks, and Web Components evolve.
 - Keep Web Component events, attributes, slots, and public APIs documented in `docs/cart-events.md`, `docs/cart-rewards.md`, `docs/cart-drawer-architecture.md`, and future extension docs.
 - Add a DTL pattern catalog for Spark-specific gotchas.
 - Decide the marketplace/self-serve release package shape.

README.md

@@ -14,9 +14,26 @@ A modern starter theme for Next Commerce. Tailwind CSS v4, vanilla JS + Web Comp
 
 ## Quick Start
 
-The compiled `assets/main.css` is committed to the repo, so NEXT developers can install Spark on a store without a local Tailwind toolchain. Clone the repo, point `ntk` at a store you control, and push.
+The compiled `assets/main.css` is committed to the repo, so NEXT developers can inspect or install Spark without a local Tailwind toolchain. Choose the path that matches what you have available.
 
-1. Install ntk and configure your store:
+### Inspect Spark Locally
+
+Use this path when you want to evaluate the theme structure, docs, and generated CSS before connecting a store.
+
+```bash
+git clone https://github.com/NextCommerceCo/spark.git
+cd spark
+python3 -m unittest discover -s tests
+python3 scripts/sass-compat.py --check assets/main.css
+```
+
+Expected time: under 2 minutes after clone on a typical laptop. This verifies the committed CSS artifact and local tooling tests. It does not render a live storefront because Spark templates run inside the Next Commerce theme runtime.
+
+### Install On A Store
+
+Use this path when you have a Next Commerce store, API key, and theme id.
+
+1. Install `ntk` and configure your store:
    ```bash
    pip install next-theme-kit
    ntk init
@@ -28,6 +45,8 @@ The compiled `assets/main.css` is committed to the repo, so NEXT developers can
    ntk push
    ```
 
+Expected time: 5-10 minutes if you already have store credentials. If `ntk` cannot find credentials, create `config.yml` with `ntk init`, copy `config.example.yml`, or pass credentials through the CLI options shown by `ntk --help`.
+
 For day-to-day development (editing CSS sources), set up Tailwind locally:
 
 ```bash
@@ -67,8 +86,10 @@ Known risky generated CSS includes `@supports`, `@property`, `@layer`, `oklch()`
 
 Avoid dynamic Tailwind class construction in templates. Tailwind scans source files at build time, so classes like `bg-{{ settings.primary_color }}` are never emitted. Use CSS custom properties (`bg-[var(--primary-color)]`) or static conditional classes instead.
 
-Troubleshooting quick read:
+## Troubleshooting
 
+- Credential errors from `ntk`: confirm `config.yml` has the API key, store domain, and theme id for a store you control.
+- Python runtime warnings before `ntk` output: retry from a current Python virtual environment. These warnings usually come from local Python packaging, not Spark.
 - Local Tailwind/build failure: `make css` fails before `assets/main.css` is written. Fix `css/input.css`, missing Tailwind binary, or local command setup.
 - Platform Sass/compiler failure: local build passes but upload/storefront errors mention CSS parsing. Run `make css-check` and inspect any unsupported construct it reports.
 - Missing uploaded compiled CSS: templates changed but styling did not. Rebuild with `make css-check`, then push `assets/main.css` explicitly.
@@ -129,6 +150,8 @@ Tracked theme documentation starts at [docs/README.md](docs/README.md). Current
 
 See [docs/theme-settings-partials.md](docs/theme-settings-partials.md) for the design-team catalog of Theme Settings partials and homepage section partials, [docs/figma-section-library-plan.md](docs/figma-section-library-plan.md) for the Spark Figma section library plan, [docs/performance-load-order.md](docs/performance-load-order.md) for the critical-path loading convention, [docs/pdp-customization.md](docs/pdp-customization.md) for the PDP redesign preservation checklist and QA runbook, [docs/pdp-variant-state.md](docs/pdp-variant-state.md) for the PDP variant state Interface, [docs/cart-events.md](docs/cart-events.md) for the cart event Interface, [docs/cart-rewards.md](docs/cart-rewards.md) for side-cart rewards and upsell rules, [docs/cart-drawer-architecture.md](docs/cart-drawer-architecture.md) for the drawer Module split, [docs/intro-bootstrap-comparison.md](docs/intro-bootstrap-comparison.md) for the Intro Bootstrap comparison, [docs/design-block-authoring.md](docs/design-block-authoring.md) for design-block authoring guidance, [docs/terminology.md](docs/terminology.md) for NEXT-native naming guardrails, and [docs/sections-architecture-proposal.md](docs/sections-architecture-proposal.md) for the future theme sections platform proposal.
 
+Start with [docs/extending-spark.md](docs/extending-spark.md) when adding Theme Settings, homepage section partials, app hooks, Web Components, or public storefront behavior.
+
 ## Design System
 
 All visual decisions are documented in [DESIGN.md](DESIGN.md) — typography, colors, spacing, motion, interaction states, accessibility, and anti-slop rules. Read it before making any UI change.
@@ -137,7 +160,7 @@ All visual decisions are documented in [DESIGN.md](DESIGN.md) — typography, co
 
 The `.gitignore` file is intentionally committed. It documents local files that must stay out of the public repository, including store-specific `config.yml`, downloaded Tailwind binaries, tool session state, OS files, and editor settings.
 
-See [SECURITY.md](SECURITY.md) for private vulnerability reporting and secrets-handling guidance.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow, [CHANGELOG.md](CHANGELOG.md) for release notes, and [SECURITY.md](SECURITY.md) for private vulnerability reporting and secrets-handling guidance.
 
 ## License
 

docs/README.md

@@ -6,6 +6,7 @@ This directory contains Spark's theme-developer, design-team, and architecture d
 
 | Doc | Audience | Purpose |
 | --- | --- | --- |
+| [extending-spark.md](extending-spark.md) | Theme developers, app developers | Supported extension surfaces for settings, partials, app hooks, events, and Web Components. |
 | [theme-settings-partials.md](theme-settings-partials.md) | Designers, theme developers | Catalog of Theme Settings-backed partials and template surfaces. |
 | [figma-section-library-plan.md](figma-section-library-plan.md) | Design team, theme developers | Plan for mapping Figma section components to Spark section authoring units. |
 | [section-specs/](section-specs/) | Design team, theme developers | Per-section specs for the current homepage section partials. |