draft-board 0.1.0-beta.0

package/app/backend/multiplication_division_implementation_tickets.json

@@ -0,0 +1,55 @@
+{
+  "tickets": [
+    {
+      "title": "Implement multiply and divide functions in calculator module",
+      "description": "Create app/utils/calculator.py with two arithmetic functions:\n\n1. multiply(a, b) - multiply two numbers\n2. divide(a, b) - divide two numbers with ZeroDivisionError handling when b is 0\n\nAll functions must:\n- Include proper type hints (use float | int for numeric types, compatible with Python 3.11+)\n- Have comprehensive docstrings following Google/NumPy style with Args, Returns, and Raises sections\n- Handle edge cases appropriately (division by zero, decimal precision)\n- Support both int and float inputs\n- Return float for divide() to ensure accurate decimal results\n- Export functions in app/utils/__init__.py\n- Follow project code style (ruff formatting, double quotes, 88 char line length)\n\nAcceptance criteria:\n- File app/utils/calculator.py exists with multiply and divide functions\n- Both functions have complete type hints (float | int for parameters, float | int for multiply return, float for divide return)\n- Both functions have docstrings with Args, Returns, and Raises sections\n- divide() raises ZeroDivisionError when divisor is 0\n- Functions are exported in app/utils/__init__.py\n- Code passes ruff linting and formatting checks\n- Functions handle both int and float inputs correctly",
+      "priority_bucket": "P1",
+      "priority_rationale": "Core feature implementation - required foundation for calculator functionality. All other tickets depend on this. High priority because it's the essential functionality needed to achieve the goal.",
+      "verification": [
+        "test -f app/utils/calculator.py",
+        "python -c 'from app.utils import multiply, divide; assert multiply(2, 3) == 6; assert divide(10, 2) == 5.0'",
+        "python -c 'from app.utils.calculator import divide; import pytest; pytest.raises(ZeroDivisionError, divide, 1, 0)'",
+        "ruff check app/utils/calculator.py"
+      ],
+      "notes": "Use standard Python operators (* and /). For type hints, Python 3.11+ supports float | int syntax. Ensure divide() returns float for accurate decimal results. Handle edge cases like multiply(0, x) and divide(x, 1)."
+    },
+    {
+      "title": "Add comprehensive test coverage for multiply and divide functions",
+      "description": "Create tests/test_calculator.py with comprehensive test coverage for multiply and divide functions.\n\nTest requirements:\n- Test normal operation with various inputs:\n  - Positive integers: multiply(2, 3), divide(10, 2)\n  - Negative numbers: multiply(-2, 3), divide(-10, 2)\n  - Decimal numbers: multiply(2.5, 4), divide(7.5, 2.5)\n  - Zero multiplication: multiply(0, 5), multiply(5, 0)\n  - Mixed types: multiply(2, 3.5), divide(10, 2.0)\n- Test error cases:\n  - ZeroDivisionError for divide(1, 0)\n  - ZeroDivisionError for divide(-5, 0)\n  - ZeroDivisionError for divide(0.0, 0)\n- Test edge cases:\n  - divide(0, 5) = 0.0\n  - multiply with very large numbers\n  - divide with very small numbers (but not zero)\n  - multiply with negative numbers (both positive, both negative, mixed)\n- Test type handling: ensure functions work with both int and float inputs and return appropriate types\n- Use pytest.raises context manager for exception testing\n- Use @pytest.mark.parametrize for testing multiple input combinations efficiently\n- Follow existing test patterns from tests/test_middleware.py\n\nAcceptance criteria:\n- File tests/test_calculator.py exists\n- Both functions have comprehensive test coverage (aim for 100% function coverage)\n- Error cases are tested and raise correct exceptions\n- Edge cases are covered\n- Tests pass with pytest -v\n- Test coverage demonstrates correct behavior for all scenarios\n- Tests use parametrize decorator where appropriate to reduce duplication",
+      "priority_bucket": "P1",
+      "priority_rationale": "Critical for ensuring code quality and preventing regressions - tests validate correctness of core functionality and catch bugs early.",
+      "verification": [
+        "test -f tests/test_calculator.py",
+        "pytest tests/test_calculator.py -v",
+        "pytest tests/test_calculator.py --cov=app.utils.calculator --cov-report=term-missing | grep -q 'multiply\\|divide'"
+      ],
+      "notes": "Use pytest.raises context manager for exception testing. Consider parametrize decorator for testing multiple input combinations efficiently. Test both int and float inputs for each function. Include tests for decimal precision handling."
+    },
+    {
+      "title": "Create API endpoint for calculator operations",
+      "description": "Create app/routers/calculator.py with FastAPI endpoints for multiply and divide operations.\n\nEndpoint requirements:\n- POST /calculator/multiply - accepts JSON body with 'a' and 'b' fields, returns result\n- POST /calculator/divide - accepts JSON body with 'a' and 'b' fields, returns result\n- Both endpoints should:\n  - Use Pydantic schemas for request/response validation (create app/schemas/calculator.py)\n  - Return appropriate HTTP status codes (200 for success, 400 for division by zero)\n  - Include proper error handling and error messages\n  - Follow existing router patterns from app/routers/goals.py\n  - Use app/exceptions.py patterns for error handling\n- Register router in app/main.py\n- Include OpenAPI documentation with examples\n\nAcceptance criteria:\n- File app/routers/calculator.py exists with both endpoints\n- File app/schemas/calculator.py exists with request/response models\n- Endpoints are registered in app/main.py\n- Request/response schemas are defined using Pydantic\n- Division by zero returns 400 status with clear error message\n- Endpoints are documented in OpenAPI/Swagger UI\n- Endpoints can be tested via curl or HTTP client",
+      "priority_bucket": "P2",
+      "priority_rationale": "Important for making calculator functionality accessible via API, but not blocking for core functionality. Users can still use the functions directly if needed. Medium priority as it enhances usability.",
+      "verification": [
+        "test -f app/routers/calculator.py",
+        "test -f app/schemas/calculator.py",
+        "grep -q 'calculator' app/main.py",
+        "curl -X POST http://localhost:8000/calculator/multiply -H 'Content-Type: application/json' -d '{\"a\": 2, \"b\": 3}' 2>/dev/null | grep -q '6' || echo 'Server may not be running - check manually'"
+      ],
+      "notes": "Follow FastAPI patterns from existing routers. Use app/schemas/calculator.py for request/response models. Consider adding GET endpoints with query parameters as alternative interface. Ensure error responses follow project error format from app/exceptions.py."
+    },
+    {
+      "title": "Enhance divide function with robust decimal precision handling",
+      "description": "Enhance the divide function in app/utils/calculator.py to properly handle decimal precision and document floating-point limitations.\n\nRequirements:\n- Ensure accurate decimal results (e.g., divide(1, 3) returns appropriate float precision)\n- Document precision limitations in docstring (floating-point arithmetic has inherent precision limitations)\n- Ensure consistent return type (always float, even for integer division results like divide(10, 2))\n- Handle very large numbers appropriately (test with sys.maxsize)\n- Handle very small numbers (near-zero divisors) appropriately - ensure near-zero positive numbers still work, but exact zero raises error\n- Add examples in docstring showing expected behavior\n- Update tests to verify decimal precision handling\n\nAcceptance criteria:\n- divide() handles decimal division accurately\n- Docstring documents precision behavior and limitations\n- divide() always returns float type (not int)\n- Function handles edge cases without errors (very large numbers, very small positive numbers)\n- Tests verify decimal precision handling\n- Documentation is clear about floating-point precision limitations",
+      "priority_bucket": "P2",
+      "priority_rationale": "Important for user experience and correctness, but not blocking - improves robustness of division operation and ensures proper decimal handling. Core functionality works without this enhancement.",
+      "verification": [
+        "python -c 'from app.utils.calculator import divide; result = divide(1, 3); assert isinstance(result, float); assert abs(result - 0.3333333333333333) < 1e-10'",
+        "python -c 'from app.utils.calculator import divide; assert isinstance(divide(10, 2), float)'",
+        "grep -q 'precision' app/utils/calculator.py || grep -q 'floating-point' app/utils/calculator.py",
+        "pytest tests/test_calculator.py -k 'decimal' -v 2>/dev/null || pytest tests/test_calculator.py -v"
+      ],
+      "notes": "Python's float division handles precision automatically. Document that floating-point arithmetic has inherent precision limitations. Consider using Decimal type for exact decimal arithmetic if needed in future enhancements, but standard float is acceptable for this implementation."
+    }
+  ]
+}

package/app/backend/multiplication_division_tickets.json

@@ -0,0 +1,42 @@
+{
+  "tickets": [
+    {
+      "title": "Implement multiply and divide functions in calculator module",
+      "description": "Create app/utils/calculator.py with two arithmetic functions:\n\n1. multiply(a, b) - multiply two numbers\n2. divide(a, b) - divide two numbers with ZeroDivisionError handling when b is 0\n\nAll functions must:\n- Include proper type hints (use float | int for numeric types, compatible with Python 3.11+)\n- Have comprehensive docstrings following Google/NumPy style with Args, Returns, and Raises sections\n- Handle edge cases appropriately (division by zero, decimal precision)\n- Support both int and float inputs\n- Return float for divide() to ensure accurate decimal results\n- Export functions in app/utils/__init__.py\n- Follow project code style (ruff formatting, double quotes, 88 char line length)\n\nAcceptance criteria:\n- File app/utils/calculator.py exists with multiply and divide functions\n- Both functions have complete type hints (float | int for parameters, float | int for multiply return, float for divide return)\n- Both functions have docstrings with Args, Returns, and Raises sections\n- divide() raises ZeroDivisionError when divisor is 0\n- Functions are exported in app/utils/__init__.py\n- Code passes ruff linting and formatting checks\n- Functions handle both int and float inputs correctly",
+      "priority_bucket": "P1",
+      "priority_rationale": "Core feature implementation - required foundation for calculator functionality. All other tickets depend on this. High priority because it's the essential functionality needed to achieve the goal.",
+      "verification": [
+        "test -f app/utils/calculator.py",
+        "python -c 'from app.utils import multiply, divide; assert multiply(2, 3) == 6; assert divide(10, 2) == 5.0'",
+        "python -c 'from app.utils.calculator import divide; import pytest; pytest.raises(ZeroDivisionError, divide, 1, 0)'",
+        "ruff check app/utils/calculator.py"
+      ],
+      "notes": "Use standard Python operators (* and /). For type hints, Python 3.11+ supports float | int syntax. Ensure divide() returns float for accurate decimal results. Handle edge cases like multiply(0, x) and divide(x, 1)."
+    },
+    {
+      "title": "Add comprehensive test coverage for multiply and divide functions",
+      "description": "Create tests/test_calculator.py with comprehensive test coverage for multiply and divide functions.\n\nTest requirements:\n- Test normal operation with various inputs:\n  - Positive integers: multiply(2, 3), divide(10, 2)\n  - Negative numbers: multiply(-2, 3), divide(-10, 2)\n  - Decimal numbers: multiply(2.5, 4), divide(7.5, 2.5)\n  - Zero multiplication: multiply(0, 5), multiply(5, 0)\n  - Mixed types: multiply(2, 3.5), divide(10, 2.0)\n- Test error cases:\n  - ZeroDivisionError for divide(1, 0)\n  - ZeroDivisionError for divide(-5, 0)\n  - ZeroDivisionError for divide(0.0, 0)\n- Test edge cases:\n  - divide(0, 5) = 0.0\n  - multiply with very large numbers\n  - divide with very small numbers (but not zero)\n  - multiply with negative numbers (both positive, both negative, mixed)\n- Test type handling: ensure functions work with both int and float inputs and return appropriate types\n- Use pytest.raises context manager for exception testing\n- Use @pytest.mark.parametrize for testing multiple input combinations efficiently\n- Follow existing test patterns from tests/test_middleware.py\n\nAcceptance criteria:\n- File tests/test_calculator.py exists\n- Both functions have comprehensive test coverage (aim for 100% function coverage)\n- Error cases are tested and raise correct exceptions\n- Edge cases are covered\n- Tests pass with pytest -v\n- Test coverage demonstrates correct behavior for all scenarios\n- Tests use parametrize decorator where appropriate to reduce duplication",
+      "priority_bucket": "P1",
+      "priority_rationale": "Critical for ensuring code quality and preventing regressions - tests validate correctness of core functionality and catch bugs early.",
+      "verification": [
+        "test -f tests/test_calculator.py",
+        "pytest tests/test_calculator.py -v",
+        "pytest tests/test_calculator.py --cov=app.utils.calculator --cov-report=term-missing | grep -q 'multiply\\|divide'"
+      ],
+      "notes": "Use pytest.raises context manager for exception testing. Consider parametrize decorator for testing multiple input combinations efficiently. Test both int and float inputs for each function. Include tests for decimal precision handling."
+    },
+    {
+      "title": "Handle decimal precision and edge cases in divide function",
+      "description": "Enhance the divide function in app/utils/calculator.py to properly handle decimal precision and edge cases.\n\nRequirements:\n- Ensure accurate decimal results (e.g., divide(1, 3) returns 0.3333333333333333)\n- Handle division by zero with clear ZeroDivisionError message\n- Handle very large numbers appropriately (test with sys.maxsize)\n- Handle very small numbers (near-zero divisors) appropriately - ensure near-zero positive numbers still work, but exact zero raises error\n- Document precision limitations in docstring (floating-point arithmetic has inherent precision limitations)\n- Ensure consistent return type (always float, even for integer division results like divide(10, 2))\n\nAcceptance criteria:\n- divide() handles decimal division accurately\n- ZeroDivisionError is raised with appropriate message for division by zero\n- Function handles edge cases without errors (very large numbers, very small positive numbers)\n- Docstring documents precision behavior and limitations\n- Tests verify decimal precision handling\n- divide() always returns float type (not int)",
+      "priority_bucket": "P2",
+      "priority_rationale": "Important for user experience and correctness, but not blocking - improves robustness of division operation and ensures proper decimal handling.",
+      "verification": [
+        "python -c 'from app.utils.calculator import divide; result = divide(1, 3); assert isinstance(result, float); assert abs(result - 0.3333333333333333) < 1e-10'",
+        "python -c 'from app.utils.calculator import divide; divide(1, 0)' 2>&1 | grep -q ZeroDivisionError",
+        "python -c 'from app.utils.calculator import divide; assert isinstance(divide(10, 2), float)'",
+        "pytest tests/test_calculator.py::test_divide_decimal_precision -v"
+      ],
+      "notes": "Python's float division handles precision automatically. Document that floating-point arithmetic has inherent precision limitations. Consider using Decimal type for exact decimal arithmetic if needed in future enhancements."
+    }
+  ]
+}

package/app/backend/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "draft-backend"
+version = "0.1.0"
+description = "Draft Backend API"
+license = {text = "BSL-1.1"}
+requires-python = ">=3.11"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # function call in default argument (standard FastAPI pattern for Depends())
+    "B904",   # raise from in except (too noisy to fix everywhere)
+    "E402",   # module level import not at top (conditional imports)
+    "E741",   # ambiguous variable name
+    "B026",   # star-arg unpacking after keyword
+    "F821",   # undefined name (false positive in dynamic imports)
+    "E722",   # bare except in test files
+    "B023",   # loop variable binding in test files
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["app"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

package/app/backend/requirements-dev.txt

@@ -0,0 +1,8 @@
+-r requirements.txt
+ruff>=0.1.14
+pytest>=7.4.0
+pytest-asyncio>=0.23.0
+httpx>=0.26.0
+
+
+gitpython

package/app/backend/requirements.txt

@@ -0,0 +1,20 @@
+fastapi>=0.109.0
+uvicorn[standard]>=0.27.0
+python-dotenv>=1.0.0
+sqlalchemy>=2.0.0
+alembic>=1.13.0
+aiosqlite>=0.19.0
+greenlet>=3.0.0
+httpx>=0.25.0
+litellm>=1.0.0
+boto3>=1.42.0  # AWS SDK for Bedrock LLM support
+sse-starlette>=2.0.0  # Server-Sent Events for real-time log streaming
+jsonpatch>=1.33  # RFC 6902 JSON Patch for incremental WebSocket updates
+langgraph>=0.2.0  # State machine agent framework for UDAR
+langchain-core>=0.3.0  # Core abstractions for LangGraph
+langchain-community>=0.3.0  # Community tools (optional)
+gitpython
+bcrypt>=4.0.0
+python-jose[cryptography]>=3.3.0
+pydantic[email]>=2.0.0  # email-validator for Pydantic EmailStr
+pyyaml>=6.0  # YAML config parsing

package/app/backend/run.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Auto-restart wrapper for uvicorn backend
+# Restarts automatically if the process dies unexpectedly
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# Activate venv if present
+if [ -f venv/bin/activate ]; then
+    source venv/bin/activate
+fi
+
+RESTART_DELAY=3
+
+echo "Starting uvicorn with auto-restart (Ctrl+C to stop)..."
+
+while true; do
+    python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --log-level info
+    EXIT_CODE=$?
+    
+    if [ $EXIT_CODE -eq 0 ]; then
+        echo "uvicorn exited cleanly (code 0). Stopping."
+        break
+    fi
+    
+    echo "uvicorn exited with code $EXIT_CODE. Restarting in ${RESTART_DELAY}s..."
+    sleep "$RESTART_DELAY"
+done

package/app/backend/run_with_logs.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Run backend with full logging to file
+
+LOG_FILE="ticket_generation_debug.log"
+
+echo "Starting backend with logging to $LOG_FILE"
+echo "Tail the log file with: tail -f $LOG_FILE"
+
+# Set Python to unbuffered mode and run uvicorn with all logs
+PYTHONUNBUFFERED=1 python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload --log-level debug 2>&1 | tee "$LOG_FILE"

package/app/backend/scientific_calculator_tickets.json

@@ -0,0 +1,40 @@
+{
+  "tickets": [
+    {
+      "title": "Create calculator.py with basic operations and extend with scientific functions",
+      "description": "Create calculator.py in the project root (or app/utils/calculator.py if following backend structure) with add() and subtract() functions if they don't exist, then add six new scientific calculator functions:\n\n1. multiply(a, b) - multiply two numbers\n2. divide(a, b) - divide two numbers, raise ZeroDivisionError when b is 0\n3. power(base, exp) - raise base to exponent power\n4. sqrt(n) - calculate square root, raise ValueError for negative numbers\n5. modulo(a, b) - remainder operation (a % b)\n6. factorial(n) - calculate factorial for non-negative integers, raise ValueError for negative numbers\n\nAll functions must:\n- Include proper type hints using float | int (or Union[float, int] for Python < 3.10)\n- Have comprehensive docstrings following Google/NumPy style with Args, Returns, and Raises sections\n- Handle edge cases appropriately (division by zero, negative sqrt, negative factorial)\n- Use math.sqrt and math.factorial from standard library where applicable\n\nAcceptance criteria:\n- calculator.py exists with all 8 functions (add, subtract, plus 6 new)\n- All functions have complete type hints\n- All functions have docstrings with Args, Returns, and Raises\n- Functions raise appropriate exceptions for invalid inputs\n- Code follows project style (ruff formatting)",
+      "priority_bucket": "P1",
+      "priority_rationale": "Core feature implementation - required foundation for calculator functionality. All other tickets depend on this.",
+      "verification": [
+        "test -f calculator.py || test -f app/utils/calculator.py",
+        "python -c 'from calculator import multiply, divide, power, sqrt, modulo, factorial; assert multiply(2, 3) == 6' || python -c 'from app.utils.calculator import multiply, divide, power, sqrt, modulo, factorial; assert multiply(2, 3) == 6'",
+        "python -c 'from calculator import divide; divide(1, 0)' 2>&1 | grep -q ZeroDivisionError || python -c 'from app.utils.calculator import divide; divide(1, 0)' 2>&1 | grep -q ZeroDivisionError"
+      ],
+      "notes": "Check if calculator.py exists in project root first. If not, create it. If following backend structure, use app/utils/calculator.py. Use math.sqrt() and math.factorial() from standard library. For modulo, use % operator. Python 3.11+ supports float | int syntax for type hints."
+    },
+    {
+      "title": "Add comprehensive test coverage for calculator functions",
+      "description": "Create tests/test_calculator.py with comprehensive test coverage for all calculator functions (add, subtract, multiply, divide, power, sqrt, modulo, factorial).\n\nTest requirements:\n- Test normal operation for each function with various positive and negative inputs\n- Test error cases:\n  - ZeroDivisionError for divide(1, 0)\n  - ValueError for sqrt(-1) and factorial(-1)\n- Test edge cases:\n  - factorial(0) = 1\n  - power(2, 0) = 1\n  - power(0, 0) = 1\n  - modulo with negative numbers\n  - divide with float results\n- Test type handling: ensure functions work with both int and float inputs\n- Use pytest.raises context manager for exception testing\n- Use @pytest.mark.parametrize for testing multiple input combinations\n- Follow existing test patterns from tests/test_middleware.py\n\nAcceptance criteria:\n- File tests/test_calculator.py exists\n- All 8 functions have test coverage\n- Error cases are tested and raise correct exceptions\n- Edge cases are covered\n- Tests pass with pytest -v\n- Test coverage is comprehensive (aim for 100% function coverage)",
+      "priority_bucket": "P1",
+      "priority_rationale": "Critical for ensuring code quality and preventing regressions - tests validate correctness of core functionality and catch bugs early.",
+      "verification": [
+        "test -f tests/test_calculator.py",
+        "pytest tests/test_calculator.py -v",
+        "pytest tests/test_calculator.py --cov=calculator --cov-report=term-missing || pytest tests/test_calculator.py --cov=app.utils.calculator --cov-report=term-missing"
+      ],
+      "notes": "Use pytest.raises context manager for exception testing. Consider parametrize decorator for testing multiple input combinations efficiently. Follow pytest patterns from existing test files like tests/test_middleware.py. Test both int and float inputs for each function."
+    },
+    {
+      "title": "Update README.md to document calculator module",
+      "description": "Update README.md in the project root to document the calculator module and its scientific operations.\n\nDocumentation should include:\n- Overview section describing the calculator module\n- List of all available functions (add, subtract, multiply, divide, power, sqrt, modulo, factorial) with brief descriptions\n- Usage examples for each function using code blocks\n- Error handling information:\n  - ZeroDivisionError for divide() when divisor is 0\n  - ValueError for sqrt() with negative numbers\n  - ValueError for factorial() with negative numbers\n- Type information (functions accept int or float, return float for most operations)\n- Link to test file (tests/test_calculator.py) for more examples\n\nAcceptance criteria:\n- README.md exists in project root\n- Calculator module section is added or updated\n- All 8 functions are documented\n- Usage examples are provided with code blocks\n- Error handling is clearly documented\n- Documentation is clear, follows project conventions, and matches existing README style",
+      "priority_bucket": "P2",
+      "priority_rationale": "Important for usability and maintainability, but not blocking for functionality - documentation helps users understand the module but code works without it.",
+      "verification": [
+        "test -f README.md",
+        "grep -qi 'calculator' README.md",
+        "grep -q 'multiply\\|divide\\|power\\|sqrt\\|modulo\\|factorial' README.md"
+      ],
+      "notes": "Add a new section to README.md for the calculator module. Include code examples using triple backticks with python syntax highlighting. Follow the existing README.md style and structure. Place the section in an appropriate location (e.g., after the main project description or in a 'Modules' section)."
+    }
+  ]
+}

package/app/backend/scripts/extract_openapi.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Extract OpenAPI JSON schema from FastAPI app without starting the server."""
+
+import json
+import sys
+from pathlib import Path
+
+# Add backend directory to path
+backend_dir = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(backend_dir))
+
+from app.main import app  # noqa: E402
+
+if __name__ == "__main__":
+    schema = app.openapi()
+    output = json.dumps(schema, indent=2)
+
+    if len(sys.argv) > 1:
+        Path(sys.argv[1]).write_text(output)
+    else:
+        print(output)

package/app/backend/scripts/seed_demo.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Seed the database with demo data for first-time users.
+
+This script creates:
+- A demo board pointing to the demo-repo
+- Demo goals with realistic descriptions (no pre-seeded tickets)
+- Ready for live ticket generation demo
+
+Run with: python -m scripts.seed_demo
+"""
+
+import asyncio
+import sys
+import uuid
+from pathlib import Path
+
+import yaml
+
+# Add backend to path so we can import app modules
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from sqlalchemy import select
+
+from app.database import async_session_maker, init_db
+from app.models.board import Board
+from app.models.goal import Goal
+from app.services.config_service import DraftConfig
+
+BOARD_ID = "demo-board"
+
+
+def _load_demo_config(demo_repo_path: Path) -> dict:
+    """Load demo-repo/draft.yaml and set dynamic paths.
+
+    Reads the YAML config and sets the yolo_allowlist to the actual
+    demo-repo path so it works on any machine.
+    """
+    yaml_path = demo_repo_path / "draft.yaml"
+    if yaml_path.exists():
+        with open(yaml_path) as f:
+            raw = yaml.safe_load(f) or {}
+    else:
+        raw = {}
+
+    # Parse through DraftConfig for proper defaults, then convert back
+    config = DraftConfig.from_dict(raw)
+    config_dict = config.to_dict()
+
+    # Set yolo_allowlist dynamically to the resolved demo-repo path
+    config_dict["execute_config"]["yolo_allowlist"] = [str(demo_repo_path)]
+
+    return config_dict
+
+
+async def seed_demo_data():
+    """Seed the database with demo board and goals (no tickets).
+
+    Creates a clean board with goals ready for live ticket generation.
+    """
+    await init_db()
+
+    async with async_session_maker() as session:
+        # Check if demo board already exists
+        result = await session.execute(select(Board).where(Board.id == BOARD_ID))
+        existing_board = result.scalar_one_or_none()
+
+        if existing_board:
+            print("Demo board already exists, skipping seed.")
+            print("Run with --clear first to reset.")
+            return
+
+        # Get the project root (where demo-repo lives)
+        project_root = Path(__file__).parent.parent.parent.resolve()
+        demo_repo_path = project_root / "demo-repo"
+
+        if not demo_repo_path.exists():
+            print(f"ERROR: demo-repo not found at {demo_repo_path}")
+            return
+
+        # Load demo config from draft.yaml and set dynamic yolo_allowlist
+        board_config = _load_demo_config(demo_repo_path)
+
+        # Create demo board
+        demo_board = Board(
+            id=BOARD_ID,
+            name="Calculator Bug Fix",
+            description=(
+                "A simple calculator app with intentional bugs. "
+                "Use the goals below to generate tickets and watch AI fix everything."
+            ),
+            repo_root=str(demo_repo_path),
+            default_branch="main",
+            config=board_config,
+        )
+        session.add(demo_board)
+
+        # --- Goals (no tickets - generate them live!) ---
+
+        goals = [
+            Goal(
+                id=str(uuid.uuid4()),
+                board_id=BOARD_ID,
+                title="Fix all calculator bugs",
+                description=(
+                    "The calculator has three critical bugs that crash the app:\n"
+                    "\n"
+                    "1. Division by zero - divide() raises ZeroDivisionError\n"
+                    "2. Negative square root - square_root() raises ValueError\n"
+                    "3. Modulo by zero - modulo() raises ZeroDivisionError\n"
+                    "\n"
+                    "Each bug needs proper error handling that returns a clear\n"
+                    "error message instead of crashing. Add tests for each fix."
+                ),
+            ),
+            Goal(
+                id=str(uuid.uuid4()),
+                board_id=BOARD_ID,
+                title="Add missing calculator features",
+                description=(
+                    "The calculator is missing several features marked as TODOs:\n"
+                    "\n"
+                    "- percentage(value, percent) - calculate percentage of a value\n"
+                    "- factorial(n) - compute n! iteratively\n"
+                    "- logarithm(x, base) - compute log with given base\n"
+                    "\n"
+                    "Each new method needs input validation and tests."
+                ),
+            ),
+        ]
+
+        for goal in goals:
+            session.add(goal)
+
+        await session.commit()
+
+        print("Demo data seeded successfully!")
+        print()
+        print(f"  Board: {demo_board.name} (ID: {BOARD_ID})")
+        print(f"  Repo:  {demo_board.repo_root}")
+        print(f"  Goals: {len(goals)}")
+        for g in goals:
+            print(f"    - {g.title}")
+        print()
+        print("Next Steps:")
+        print("  1. make run")
+        print("  2. Open http://localhost:5173")
+        print("  3. Select the 'Calculator Bug Fix' board")
+        print("  4. Click a goal -> 'Generate Tickets'")
+        print()
+
+
+async def clear_demo_data():
+    """Clear demo data (useful for resetting)."""
+    await init_db()
+
+    async with async_session_maker() as session:
+        result = await session.execute(select(Board).where(Board.id == BOARD_ID))
+        demo_board = result.scalar_one_or_none()
+
+        if demo_board:
+            await session.delete(demo_board)
+            await session.commit()
+            print("Demo data cleared.")
+        else:
+            print("No demo data found.")
+
+
+def main():
+    """Main entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Seed demo data for Draft")
+    parser.add_argument(
+        "--clear",
+        action="store_true",
+        help="Clear existing demo data instead of seeding",
+    )
+    args = parser.parse_args()
+
+    if args.clear:
+        asyncio.run(clear_demo_data())
+    else:
+        asyncio.run(seed_demo_data())
+
+
+if __name__ == "__main__":
+    main()