fix(dx): resolve issues #736, #737, #738, #739 — templates, script, SQL tracking

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug Report
+about: Report a reproducible bug
+labels: bug
+---
+
+## Description
+
+<!-- A clear and concise description of the bug. -->
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+<!-- What should happen? -->
+
+## Actual Behavior
+
+<!-- What actually happens? Include error messages or screenshots if relevant. -->
+
+## Environment
+
+- OS:
+- Browser / Runtime version:
+- Relevant service (api / frontend / tts / contracts):
+- Commit / version:
+
+## Additional Context
+
+<!-- Any other information that might help. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature Request
+about: Propose a new feature or improvement
+labels: enhancement
+---
+
+## Problem Statement
+
+<!-- What problem does this feature solve? Who is affected? -->
+
+## Proposed Solution
+
+<!-- Describe the feature you'd like. Be as specific as possible. -->
+
+## Alternatives Considered
+
+<!-- What other approaches did you consider, and why did you rule them out? -->
+
+## Additional Context
+
+<!-- Mockups, references, related issues, or any other context. -->

.github/pull_request_template.md

@@ -0,0 +1,26 @@
+## Description
+
+<!-- What does this PR do? Why is it needed? -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / code cleanup
+- [ ] Documentation update
+- [ ] CI / tooling change
+- [ ] Breaking change
+
+## Testing Done
+
+<!-- Describe how you tested this change. -->
+
+## Checklist
+
+- [ ] Tests pass locally
+- [ ] Documentation updated (if applicable)
+- [ ] No breaking changes, or breaking changes are documented above
+
+## Related Issues
+
+Closes #

push_and_create_pr.sh

@@ -1,75 +1,64 @@
 #!/bin/bash
-
-# Script to push branch and create PR for Issue #14
-# Run this from the project root: bash push_and_create_pr.sh
+# push_and_create_pr.sh — push current branch and open a PR via GitHub CLI.
+# Usage: bash push_and_create_pr.sh [--help]
 
 set -e
 
-echo "╔══════════════════════════════════════════════════════════════╗"
-echo "║  Pushing Issue #14 Branch and Creating Pull Request         ║"
-echo "╚══════════════════════════════════════════════════════════════╝"
-echo ""
+usage() {
+    cat <<EOF
+Usage: bash push_and_create_pr.sh [--help]
 
-# Check if we're on the correct branch
-CURRENT_BRANCH=$(git branch --show-current)
-EXPECTED_BRANCH="features/issue-14-Permissioned-Creation-Tiered-Market-Levels"
+Pushes the current branch to origin and creates a GitHub Pull Request.
+
+Requirements:
+  - gh CLI installed and authenticated (https://cli.github.com/)
+  - Must be run from inside the git repository
+
+Options:
+  --help    Show this help message and exit
+EOF
+    exit 0
+}
 
-if [ "$CURRENT_BRANCH" != "$EXPECTED_BRANCH" ]; then
-    echo "❌ Error: Not on the correct branch"
-    echo "   Current: $CURRENT_BRANCH"
-    echo "   Expected: $EXPECTED_BRANCH"
+[[ "${1:-}" == "--help" ]] && usage
+
+# Validate gh CLI is installed
+if ! command -v gh &>/dev/null; then
+    echo "❌ Error: 'gh' CLI is not installed."
+    echo "   Install it from https://cli.github.com/ then run: gh auth login"
     exit 1
 fi
 
-echo "✅ On correct branch: $CURRENT_BRANCH"
-echo ""
+# Validate gh CLI is authenticated
+if ! gh auth status &>/dev/null; then
+    echo "❌ Error: 'gh' CLI is not authenticated."
+    echo "   Run: gh auth login"
+    exit 1
+fi
 
-# Show commits to be pushed
-echo "📦 Commits to be pushed:"
-git log --oneline -2
-echo ""
+# Derive repo from git remote (works after forks/renames)
+REPO=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+/[^/]+)(\.git)?$|\1|')
+CURRENT_BRANCH=$(git branch --show-current)
 
-# Push the branch
-echo "🚀 Pushing branch to origin..."
-git push origin "$CURRENT_BRANCH"
+if [[ -z "$CURRENT_BRANCH" ]]; then
+    echo "❌ Error: Could not determine current branch (detached HEAD?)."
+    exit 1
+fi
+
+echo "📦 Repository : $REPO"
+echo "🌿 Branch     : $CURRENT_BRANCH"
 echo ""
 
-echo "✅ Branch pushed successfully!"
+echo "🚀 Pushing branch to origin..."
+git push -u origin "$CURRENT_BRANCH"
 echo ""
 
-# Check if gh CLI is available
-if command -v gh &> /dev/null; then
-    echo "📝 GitHub CLI detected. Creating PR..."
-    echo ""
-
-    # Create PR using gh CLI
-    gh pr create \
-        --base main \
-        --title "feat: Permissioned Creation & Tiered Market Levels (Issue #14)" \
-        --body-file PR_TEMPLATE_ISSUE_14.md \
-        --label "enhancement" \
-        --label "breaking-change"
-
-    echo ""
-    echo "✅ Pull Request created successfully!"
-else
-    echo "ℹ️  GitHub CLI not found. Please create PR manually:"
-    echo ""
-    echo "1. Visit your repository on GitHub"
-    echo "2. Click 'Compare & pull request' button"
-    echo "3. Set base branch to: main (or develop if it exists)"
-    echo "4. Copy content from PR_TEMPLATE_ISSUE_14.md into PR description"
-    echo "5. Add labels: enhancement, breaking-change"
-    echo ""
-    echo "Or install GitHub CLI: https://cli.github.com/"
-fi
+echo "📝 Creating Pull Request..."
+gh pr create \
+    --repo "$REPO" \
+    --base main \
+    --head "$CURRENT_BRANCH" \
+    --fill
 
 echo ""
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "📚 Documentation files available:"
-echo "   • IMPLEMENTATION_ISSUE_14.md"
-echo "   • PR_TEMPLATE_ISSUE_14.md"
-echo "   • QUICK_REFERENCE_ISSUE_14.md"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo ""
-echo "✨ Done!"
+echo "✅ Done!"

services/api/DATABASE.md

@@ -18,22 +18,36 @@ This service uses PostgreSQL. Schema and seed scripts are in:
 
 ## Migration Files
 
-1. `001_enable_pgcrypto.sql`
-2. `002_create_newsletter_subscriptions.sql` — creates `newsletter_subscribers` table
-3. `003_create_contact_form_submissions.sql`
-4. `004_create_waitlist_entries.sql`
-5. `005_create_content_management.sql`
-6. `006_create_analytics_events.sql`
-7. `007_create_audit_logs.sql`
-8. `008_create_email_tracking.sql`
-9. `009_add_newsletter_indexes.sql` — performance indexes on `newsletter_subscribers`
-10. `010_create_audit_log.sql` — append-only `audit_log` table for admin operations
+1. `000_create_schema_migrations.sql`
+2. `001_enable_pgcrypto.sql`
+3. `002_create_newsletter_subscriptions.sql` — creates `newsletter_subscribers` table
+4. `003_create_contact_form_submissions.sql`
+5. `004_create_waitlist_entries.sql`
+6. `005_create_content_management.sql`
+7. `006_create_analytics_events.sql`
+8. `007_create_audit_logs.sql`
+9. `008_create_email_tracking.sql`
+10. `009_add_newsletter_indexes.sql` — performance indexes on `newsletter_subscribers`
 11. `010_add_soft_delete_newsletter.sql` — adds `deleted_at` to `newsletter_subscribers`
+12. `010_create_audit_log.sql` — append-only `audit_log` table for admin operations
+13. `011_create_markets.sql` — creates `markets` table
+14. `012_add_performance_indexes.sql` — composite indexes on `markets` and `content` (promoted from `sql/`)
 
 > **Note:** Two migration files share the `010_` prefix. Apply them in lexicographic
 > order (`010_add_soft_delete_newsletter.sql` before `010_create_audit_log.sql`) or
 > rename one to `011_` to avoid ambiguity with migration runners that sort by filename.
 
+## sql/ Directory
+
+`services/api/sql/` contains **query templates and ad-hoc reference SQL** — not schema migrations.
+
+| File | Purpose |
+|---|---|
+| `performance_indexes.sql` | Source for the indexes now in `012_add_performance_indexes.sql`. Kept as a reference; do not apply manually. |
+| `newsletter_schema.sql` | Early draft of the `newsletter_subscribers` schema. Superseded by `002_create_newsletter_subscriptions.sql`. Do not apply manually. |
+
+> **Rule:** No schema-altering SQL should be applied from `sql/` directly. All schema changes must go through a numbered migration in `database/migrations/`.
+
 ## Connection Pool Configuration
 
 Pool sizing and timeouts are fully env-configurable — no code changes needed for different deployment sizes.

services/api/database/migrations/012_add_performance_indexes.sql

@@ -0,0 +1,8 @@
+-- Migration: performance indexes for markets and content tables.
+-- Promoted from sql/performance_indexes.sql into the migration system.
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_markets_status_volume_ends_at
+ON markets (status, total_volume DESC, ends_at ASC);
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_content_published_at
+ON content (is_published, published_at DESC);