kollabor 0.4.9__py3-none-any.whl → 0.4.15__py3-none-any.whl

agents/technical-writer/tutorial-creation.md

@@ -0,0 +1,1448 @@
+<!-- Tutorial Creation skill - write effective step-by-step tutorials -->
+
+tutorial-creation mode: LEARN BY DOING
+
+when this skill is active, you follow tutorial writing best practices.
+this is a comprehensive guide to creating effective technical tutorials.
+
+
+PHASE 0: AUDIENCE ANALYSIS
+
+before writing ANY tutorial, understand who will read it.
+
+
+identify target audience
+
+ask these questions:
+
+  [ ] what is their skill level?
+      beginner - needs explanations of basic concepts
+      intermediate - knows basics, needs practical application
+      advanced - needs optimization and edge cases
+
+  [ ] what is their goal?
+      learn a new technology
+      solve a specific problem
+      build a complete project
+      integrate with existing system
+
+  [ ] what do they already know?
+      programming languages
+      frameworks or tools
+      domain knowledge
+      related technologies
+
+  [ ] what is their learning style?
+      hands-on learners prefer code examples
+      conceptual learners prefer explanations
+      visual learners prefer diagrams
+
+  [ ] how much time do they have?
+      quick tutorial: 15-30 minutes
+      medium tutorial: 1-2 hours
+      long tutorial: half-day or multiple sessions
+
+
+create audience persona
+
+define a specific reader:
+
+  target audience:
+    - role: junior developer
+    - experience: 1-2 years
+    - knows: python basics, git fundamentals
+    - doesn't know: web frameworks, api design
+    - goal: build first rest api
+    - available time: ~2 hours
+
+write for this persona specifically.
+when you try to write for everyone, you write for no one.
+
+
+check for existing tutorials
+
+  <terminal>find docs -name "*tutorial*" -o -name "*guide*" 2>/dev/null</terminal>
+  <terminal>find docs -name "*getting*started*" 2>/dev/null</terminal>
+  <terminal>ls docs/tutorials/ 2>/dev/null || echo "no tutorials directory"</terminal>
+
+read existing tutorials to understand:
+  - format and structure in use
+  - writing style and tone
+  - what topics are covered
+  - what's missing
+
+fill gaps, don't duplicate.
+
+
+check for related documentation
+
+  <terminal>find docs -name "README*" -o -name "architecture*" -o -name "api*" 2>/dev/null</terminal>
+
+link to related docs:
+  - API reference
+  - architecture documentation
+  - conceptual guides
+  - troubleshooting guides
+
+tutorials should complement, not replace, reference docs.
+
+
+PHASE 1: TUTORIAL OBJECTIVES
+
+define clear, measurable learning objectives.
+
+
+define the goal
+
+what will the reader be able to DO after completing the tutorial?
+
+  good objectives:
+    - build a rest api with user authentication
+    - deploy a serverless function to aws
+    - create a real-time chat application
+    - integrate payment processing
+
+  bad objectives:
+    - learn about frameworks (too vague)
+    - understand the system (not actionable)
+    - know everything (impossible)
+
+
+write SMART objectives
+
+  [ ] Specific - exact skill to be learned
+  [ ] Measurable - can test if achieved
+  [ ] Achievable - realistic for the time
+  [ ] Relevant - valuable to the reader
+  [ ] Time-bound - fits in promised duration
+
+  example:
+    after this tutorial, you will:
+      [ ] create a fastapi project from scratch
+      [ ] define 5 rest endpoints with proper http methods
+      [ ] implement jwt authentication
+      [ ] write tests for all endpoints
+      [ ] deploy to a cloud platform
+
+
+define prerequisites
+
+be explicit about what readers need before starting:
+
+  prerequisites:
+    knowledge:
+      [ ] python programming basics
+      [ ] understanding of http methods (get, post, put, delete)
+      [ ] basic git commands
+
+    tools:
+      [ ] python 3.11 or later installed
+      [ ] code editor (vs code, pycharm, etc.)
+      [ ] git installed
+      [ ] postman or similar api testing tool
+
+    accounts:
+      [ ] github account
+      [ ] free tier cloud account
+
+  setup instructions for prerequisites:
+    <terminal>python --version</terminal>
+    <terminal>git --version</terminal>
+
+  if any check fails, provide setup links.
+
+
+define scope
+
+what will and won't be covered:
+
+  in scope:
+    - building a rest api with fastapi
+    - sqlite database with sqlalchemy
+    - jwt authentication
+    - docker containerization
+    - basic deployment
+
+  out of scope:
+    - production database setup
+    - advanced authentication (oauth, 2fa)
+    - caching strategies
+    - monitoring and logging
+    - ci/cd pipelines
+
+  link to resources for out-of-scope topics.
+
+
+PHASE 2: TUTORIAL STRUCTURE
+
+effective tutorials follow a proven structure.
+
+
+the tutorial outline
+
+  title: [clear, action-oriented]
+  subtitle: [what will be built and how long it takes]
+
+  introduction:
+    - what you'll build
+    - why it matters
+    - who it's for
+    - what you'll learn
+    - time estimate
+
+  prerequisites:
+    - knowledge needed
+    - tools required
+    - setup instructions
+
+  overview:
+    - high-level architecture
+    - components to be built
+    - final result preview
+
+  steps (progressive):
+    1. project setup
+    2. basic implementation
+    3. core functionality
+    4. advanced features
+    5. testing
+    6. deployment
+
+  summary:
+    - what was accomplished
+    - next steps
+    - related tutorials
+
+
+introduction section
+
+hook the reader immediately:
+
+  what you'll build
+  ---------------
+  in this tutorial, you'll build a complete rest api for a task
+  management application. users will be able to:
+
+    - create accounts and authenticate
+    - create, read, update, and delete tasks
+    - organize tasks by project
+    - set due dates and priorities
+
+  by the end, you'll have a production-ready api deployed to the cloud.
+
+  why this matters
+  ---------------
+  building apis is a fundamental skill for backend development.
+  the patterns you'll learn here apply to any api project:
+
+    - proper endpoint design
+    - authentication and authorization
+    - data validation
+    - error handling
+    - testing and deployment
+
+  who this is for
+  --------------
+  this tutorial is for developers who:
+
+    - know python basics
+    - want to learn backend development
+    - need to build apis for their projects
+    - have 2-3 hours to complete it
+
+  what you'll learn
+  -----------------
+    - fastapi framework fundamentals
+    - database modeling with sqlalchemy
+    - jwt authentication implementation
+    - input validation and error handling
+    - unit and integration testing
+    - containerization with docker
+    - cloud deployment basics
+
+
+PHASE 3: THE FIRST STEP
+
+the first step determines if readers continue.
+
+
+project setup
+
+make setup foolproof with verification:
+
+  step 1: create the project
+  ---------------------------
+
+  create a new directory for your project:
+
+    <terminal>mkdir task-api</terminal>
+    <terminal>cd task-api</terminal>
+
+  create a virtual environment:
+
+    <terminal>python -m venv venv</terminal>
+
+  activate it:
+
+    on mac/linux:
+      <terminal>source venv/bin/activate</terminal>
+
+    on windows:
+      <terminal>venv\Scripts\activate</terminal>
+
+  verify activation:
+    <terminal>which python</terminal>
+
+  you should see the path to your venv python, not the system python.
+
+
+install dependencies
+
+  create a requirements.txt file:
+
+    <create>
+    <file>requirements.txt</file>
+    <content>
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+sqlalchemy==2.0.25
+pydantic==2.5.3
+pydantic-settings==2.1.0
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+python-multipart==0.0.6
+pytest==7.4.4
+httpx==0.26.0
+    </content>
+    </create>
+
+  install dependencies:
+
+    <terminal>pip install -r requirements.txt</terminal>
+
+  verify installation:
+
+    <terminal>pip list | grep fastapi</terminal>
+    <terminal>pip list | grep uvicorn</terminal>
+
+
+create project structure
+
+  <terminal>mkdir -p app/{api,core,models,schemas,services}</terminal>
+  <terminal>mkdir -p tests</terminal>
+
+  your directory should now look like:
+
+    task-api/
+    ├── app/
+    │   ├── api/          # api endpoints
+    │   ├── core/         # configuration
+    │   ├── models/       # database models
+    │   ├── schemas/      # pydantic schemas
+    │   └── services/     # business logic
+    ├── tests/            # tests
+    └── requirements.txt
+
+  verify structure:
+
+    <terminal>ls -r app/</terminal>
+
+
+create a hello world
+
+start with something that works:
+
+  create the main application file:
+
+    <create>
+    <file>app/main.py</file>
+    <content>
+from fastapi import fastapi
+
+app = fastapi(title="task api")
+
+@app.get("/")
+def read_root():
+    return {"message": "welcome to task api"}
+    </content>
+    </create>
+
+  run the application:
+
+    <terminal>uvicorn app.main:app --reload</terminal>
+
+  you should see:
+
+    info:     started server process
+    info:     waiting for application startup.
+    info:     application startup complete.
+    info:     uvicorn running on http://127.0.0.1:8000
+
+  open http://127.0.0.1:8000 in your browser.
+
+  you should see:
+    {"message": "welcome to task api"}
+
+  [ok] if you see this message, you're ready to continue!
+  [x] if you see an error, check the troubleshooting section below.
+
+
+verify each step
+
+after every step, provide a verification:
+
+  verification:
+    <terminal>curl http://127.0.0.1:8000/</terminal>
+
+  expected output:
+    {"message":"welcome to task api"}
+
+  [ ] if this works, continue to the next step
+  [ ] if not, see troubleshooting below
+
+
+troubleshooting for step 1
+
+  problem: "module not found" error
+  solution: make sure virtual environment is activated
+    <terminal>source venv/bin/activate</terminal>
+    <terminal>pip install -r requirements.txt</terminal>
+
+  problem: port 8000 already in use
+  solution: use a different port
+    <terminal>uvicorn app.main:app --reload --port 8001</terminal>
+
+  problem: command not found: uvicorn
+  solution: install uvicorn
+    <terminal>pip install uvicorn[standard]</terminal>
+
+
+PHASE 4: BUILDING PROGRESSIVELY
+
+each step builds on the previous.
+
+
+complexity progression
+
+  step 1: hello world (5 min)
+    - verify setup works
+
+  step 2: single endpoint (10 min)
+    - create one read endpoint
+    - understand the request/response cycle
+
+  step 3: full crud (20 min)
+    - create, read, update, delete operations
+    - understand http methods
+
+  step 4: database integration (20 min)
+    - connect to database
+    - persist data
+
+  step 5: data models (15 min)
+    - define proper schema
+    - add relationships
+
+  step 6: validation (15 min)
+    - input validation
+    - error handling
+
+  step 7: authentication (20 min)
+    - user registration
+    - login and tokens
+
+  step 8: authorization (10 min)
+    - protect endpoints
+    - user-specific data
+
+  step 9: testing (20 min)
+    - unit tests
+    - integration tests
+
+  step 10: deployment (15 min)
+    - containerize
+    - deploy to cloud
+
+total: ~2.5 hours
+
+
+building - each endpoint
+
+when teaching a new concept:
+
+  [1] explain what we're building
+  [2] show the code
+  [3] explain how it works
+  [4] run and verify
+  [5] explain what could go wrong
+
+  example - adding a create endpoint:
+
+  step 4: create tasks
+  -------------------
+
+  we need an endpoint to create tasks. let's add it.
+
+  add the pydantic schema for task creation:
+
+    <edit>
+    <file>app/schemas/tasks.py</file>
+    <find>from pydantic import basemodel</find>
+    <replace>
+from pydantic import basemodel, fieldvalidator
+from datetime import datetime
+from enum import enum
+
+class priority(str, enum):
+    low = "low"
+    medium = "medium"
+    high = "high"
+
+class taskcreate(basemodel):
+    title: str
+    description: str | none = none
+    priority: priority = priority.medium
+    due_date: datetime | none = none
+
+    @fieldvalidator("title")
+    @classmethod
+    def title_not_empty(cls, v):
+        if not v or not v.strip():
+            raise valueerror("title cannot be empty")
+        return v.strip()
+    </replace>
+    </edit>
+
+  add the endpoint:
+
+    <edit>
+    <file>app/api/tasks.py</file>
+    <find>@app.get("/tasks")</find>
+    <replace>
+@app.post("/tasks", status_code=201)
+def create_task(task: taskcreate):
+    """create a new task."""
+    new_task = {
+        "id": len(tasks) + 1,
+        **task.model_dump(),
+        "created_at": datetime.now(),
+        "completed": false
+    }
+    tasks.append(new_task)
+    return new_task
+
+@app.get("/tasks")</replace>
+    </edit>
+
+  how it works:
+    - the @post decorator defines a post endpoint
+    - status_code=201 returns "created" status
+    - fastapi validates the request against taskcreate schema
+    - invalid requests return 422 with validation errors
+    - we return the created task with its new id
+
+  test it:
+
+    <terminal>curl -x post http://127.0.0.1:8000/tasks \
+      -h "content-type: application/json" \
+      -d '{"title": "write documentation", "priority": "high"}'</terminal>
+
+  response:
+    {
+      "id": 1,
+      "title": "write documentation",
+      "description": null,
+      "priority": "high",
+      "due_date": null,
+      "created_at": "2024-01-25t10:30:00",
+      "completed": false
+    }
+
+  [ok] if you see the created task, continue!
+  [x] if you see an error, check below.
+
+
+error responses
+
+show what happens with invalid input:
+
+  test validation:
+    <terminal>curl -x post http://127.0.0.1:8000/tasks \
+      -h "content-type: application/json" \
+      -d '{"title": ""}'</terminal>
+
+  response:
+    {
+      "detail": [
+        {
+          "loc": ["body", "title"],
+          "msg": "title cannot be empty",
+          "type": "value_error"
+        }
+      ]
+    }
+
+  the validation automatically protects your endpoint from bad data.
+  this is one of fastapi's superpowers.
+
+
+PHASE 5: CHECKPOINTS AND VERIFICATION
+
+readers need to verify progress.
+
+
+checkpoint structure
+
+after each major section, add a checkpoint:
+
+  checkpoint: basic api working
+  ----------------------------
+
+  at this point, you should have:
+    [ ] a running fastapi server
+    [ ] a working /tasks endpoint (get)
+    [ ] a working /tasks endpoint (post)
+    [ ] data validation on create
+
+  verify everything works:
+
+    <terminal>curl http://127.0.0.1:8000/tasks</terminal>
+
+    <terminal>curl -x post http://127.0.0.1:8000/tasks \
+      -h "content-type: application/json" \
+      -d '{"title": "test task"}'</terminal>
+
+  expected results:
+    - first call returns the list of tasks
+    - second call returns the new task
+
+  [ ] if both work, continue to the next section
+  [ ] if not, review the previous steps
+
+
+save your progress
+
+encourage readers to commit after each checkpoint:
+
+  git checkpoint:
+
+    <terminal>git add .</terminal>
+    <terminal>git commit -m "add basic task endpoints"</terminal>
+
+  this creates a recovery point.
+  if something breaks later, you can always return.
+
+
+PHASE 6: EXPLAINING CONCEPTS
+
+balance theory and practice.
+
+
+the concept sandwich
+
+  [1] show what we're building (motivation)
+  [2] explain the concept briefly (theory)
+  [3] show the code (practice)
+  [4] explain how the code implements the concept
+  [5] show it working (verification)
+
+  example - explaining authentication:
+
+  why authentication matters:
+  ---------------
+  right now, anyone can create, read, or delete tasks.
+  we need to know who is making requests so:
+    - users only see their own tasks
+    - users can't delete other users' tasks
+    - we can track who created what
+
+  how jwt authentication works:
+  ---------------
+  jwt (json web token) authentication works like this:
+
+    1. user sends credentials (email/password)
+    2. server verifies credentials
+    3. server creates a token with user info
+    4. server signs the token with a secret key
+    5. server sends token back to user
+    6. user includes token in subsequent requests
+    7. server verifies token signature
+    8. server extracts user info from token
+
+  the token is stateless - the server doesn't need to store sessions.
+  it just verifies the signature is valid.
+
+  implementing authentication:
+  ---------------
+  [code implementation...]
+
+  testing authentication:
+  ---------------
+  [verification steps...]
+
+
+concept depth guidelines
+
+  how much to explain?
+
+  for beginners:
+    - explain the concept fully
+    - use analogies
+    - show diagrams
+    - explain every line of code
+
+  for intermediate:
+    - explain the key concepts
+    - focus on why, not just what
+    - explain non-obvious code
+    - link to deeper resources
+
+  for advanced:
+    - brief concept overview
+    - focus on implementation details
+    - discuss trade-offs
+    - show alternatives
+
+
+diagrams and visuals
+
+create ascii diagrams for clarity:
+
+  request flow:
+  -------------
+  client --> nginx --> fastapi --> database
+    |         |         |          |
+    |         |         |          +---> postgresql
+    |         |         |
+    |         |         +---> business logic
+    |         |               |
+    |         |               +---> validation
+    |         |               +---> authorization
+    |         |
+    |         +---> ssl termination
+    |
+    +---> browser/postman
+
+
+authentication flow:
+-------------------
+
+login:
+  user                api                database
+   |                   |                    |
+   |--creds----------->|                    |
+   |                   |--verify----------->|
+   |                   |<------found--------|
+   |                   |                    |
+   |<---token----------|                    |
+   |                   |                    |
+
+authenticated request:
+  user                api
+   |                   |
+   |--request+token--->|
+   |                   |--verify signature
+   |                   |--extract user id
+   |<---response-------|
+
+
+PHASE 7: CODE QUALITY IN TUTORIALS
+
+tutorial code should be production-quality.
+
+
+best practices in examples
+
+  [ ] type hints
+      def create_user(user: usercreate) -> user:
+          ...
+
+  [ ] validation
+      use pydantic for input validation
+      never trust user input
+
+  [ ] error handling
+      return proper error codes
+      include helpful error messages
+
+  [ ] security
+      hash passwords
+      validate input
+      use environment variables for secrets
+
+  [ ] testing
+      show how to test what you build
+      include test examples
+
+  [ ] documentation
+      docstrings for functions
+      comments for complex logic
+
+
+what to skip in tutorials
+
+for brevity, you can skip:
+
+  [ ] extensive logging
+      mention it exists, don't show every log line
+
+  [ ] comprehensive error handling
+      show the pattern, don't handle every edge case
+
+  [ ] full test coverage
+      show test examples, don't test every case
+
+  [ ] production configuration
+      show development config, mention production needs
+
+  add a note when skipping:
+
+  note: in production, you would also want:
+    - structured logging
+    - more comprehensive error handling
+    - additional monitoring
+    - rate limiting
+
+
+PHASE 8: TESTING SECTION
+
+teach readers to test their work.
+
+
+unit testing
+
+show how to test individual components:
+
+  step 9: testing
+  --------------
+
+  first, install test dependencies:
+
+    <terminal>pip install pytest pytest-cov httpx</terminal>
+
+  create a test file:
+
+    <create>
+    <file>tests/test_tasks.py</file>
+    <content>
+import pytest
+from fastapi.testclient import testclient
+from app.main import app
+
+client = testclient(app)
+
+def test_create_task():
+    """test creating a new task."""
+    response = client.post(
+        "/tasks",
+        json={
+            "title": "test task",
+            "priority": "high"
+        }
+    )
+
+    assert response.status_code == 201
+    data = response.json()
+    assert data["title"] == "test task"
+    assert data["priority"] == "high"
+    assert "id" in data
+
+def test_create_task_with_empty_title():
+    """test that empty title is rejected."""
+    response = client.post(
+        "/tasks",
+        json={"title": ""}
+    )
+
+    assert response.status_code == 422
+    assert "title" in response.json()["detail"][0]["loc"]
+
+def test_get_tasks():
+    """test retrieving the task list."""
+    # first create a task
+    client.post("/tasks", json={"title": "test task"})
+
+    # then get all tasks
+    response = client.get("/tasks")
+
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data) > 0
+    </content>
+    </create>
+
+  run the tests:
+
+    <terminal>pytest tests/test_tasks.py -v</terminal>
+
+  expected output:
+    tests/test_tasks.py::test_create_task passed
+    tests/test_tasks.py::test_create_task_with_empty_title passed
+    tests/test_tasks.py::test_get_tasks passed
+
+  [ok] if all tests pass, your api is working correctly!
+  [x] if any test fails, review the error and fix your code
+
+
+integration testing
+
+show how to test the full flow:
+
+  <create>
+  <file>tests/test_integration.py</file>
+  <content>
+import pytest
+from fastapi.testclient import testclient
+from app.main import app
+
+client = testclient(app)
+
+def test_full_task_workflow():
+    """test complete create-read-update-delete workflow."""
+    # create
+    response = client.post(
+        "/tasks",
+        json={"title": "integration test task"}
+    )
+    assert response.status_code == 201
+    task_id = response.json()["id"]
+
+    # read
+    response = client.get(f"/tasks/{task_id}")
+    assert response.status_code == 200
+    assert response.json()["title"] == "integration test task"
+
+    # update
+    response = client.put(
+        f"/tasks/{task_id}",
+        json={"title": "updated task", "completed": true}
+    )
+    assert response.status_code == 200
+    assert response.json()["completed"] is true
+
+    # delete
+    response = client.delete(f"/tasks/{task_id}")
+    assert response.status_code == 200
+
+    # verify deleted
+    response = client.get(f"/tasks/{task_id}")
+    assert response.status_code == 404
+  </content>
+  </create>
+
+
+PHASE 9: DEPLOYMENT
+
+help readers get their work into the world.
+
+
+deployment checklist
+
+  [ ] containerize the application
+  [ ] configure environment variables
+  [ ] set up database
+  [ ] deploy to platform
+  [ ] verify deployment
+  [ ] set up monitoring
+
+
+docker deployment
+
+  step 10: deploy
+  --------------
+
+  create a dockerfile:
+
+    <create>
+    <file>dockerfile</file>
+    <content>
+from python:3.11-slim
+
+workdir /app
+
+copy requirements.txt .
+run pip install --no-cache-dir -r requirements.txt
+
+copy . .
+
+expose 8000
+
+cmd ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+    </content>
+    </create>
+
+  build the image:
+
+    <terminal>docker build -t task-api .</terminal>
+
+  run the container:
+
+    <terminal>docker run -p 8000:8000 task-api</terminal>
+
+  verify it's running:
+
+    <terminal>curl http://127.0.0.1:8000/</terminal>
+
+
+cloud deployment
+
+provide at least one cloud deployment option:
+
+  deploy to railway (simple):
+
+    <terminal>npm install -g railway</terminal>
+    <terminal>railway login</terminal>
+    <terminal>railway init</terminal>
+    <terminal>railway up</terminal>
+
+  or deploy to render:
+
+    1. create a render.com account
+    2. create new web service
+    3. connect your github repository
+    4. render auto-deploys on push
+
+  add a render.yaml to your repo:
+
+    <create>
+    <file>render.yaml</file>
+    <content>
+services:
+  - type: web
+    name: task-api
+    runtime: docker
+    plan: free
+    envvars:
+      - key: database_url
+        fromdatabase:
+          name: task-db
+          property: connectionstring
+databases:
+  - name: task-db
+    databaseName: taskdb
+    user: taskuser
+  </content>
+    </create>
+
+
+PHASE 10: COMMON PITFALLS
+
+help readers avoid mistakes.
+
+
+pitfall warnings
+
+add warning boxes for common mistakes:
+
+  warning: don't commit secrets
+  --------------------------
+  never commit api keys, passwords, or tokens to git.
+
+  instead, use environment variables:
+
+    <create>
+    <file>.env</file>
+    <content>
+    database_url=postgresql://user:pass@localhost/dbname
+    secret_key=your-secret-key-here
+    </content>
+    </create>
+
+  and add .env to .gitignore:
+
+    <terminal>echo ".env" >> .gitignore</terminal>
+
+  warning: default secret keys
+  --------------------------
+  never use default secret keys in production.
+
+  generate a secure key:
+
+    <terminal>python -c "import secrets; print(secrets.token_urlsafe(32))"</terminal>
+
+  warning: sqlite in production
+  ---------------------------
+  sqlite is fine for development but not for production.
+  use postgresql or mysql for production deployments.
+
+
+PHASE 11: TROUBLESHOOTING
+
+help readers when things go wrong.
+
+
+common issues
+
+  common issues:
+  -------------
+
+  issue: "address already in use" error
+  solution: another process is using port 8000
+    <terminal>lsof -i :8000</terminal>
+    <terminal>kill -9 <pid></terminal>
+
+  issue: "module not found: fastapi"
+  solution: make sure virtual environment is activated
+    <terminal>source venv/bin/activate</terminal>
+    <terminal>pip install -r requirements.txt</terminal>
+
+  issue: tests pass but curl fails
+  solution: make sure the server is running
+    <terminal>uvicorn app.main:app --reload</terminal>
+
+  issue: database errors after restart
+  solution: make sure database migration ran
+    <terminal>alembic upgrade head</terminal>
+
+
+debug mode section
+
+show how to enable debug output:
+
+  enable debug logging:
+
+    <edit>
+    <file>app/main.py</file>
+    <find>import logging</find>
+    <replace>
+import logging
+
+logging.basicConfig(level=logging.debug)
+logger = logging.getlogger(__name__)
+    </replace>
+    </edit>
+
+  add debug endpoints:
+
+    @app.get("/debug/health")
+    def health_check():
+        return {
+            "status": "healthy",
+            "database": db_connected(),
+            "redis": cache_connected()
+        }
+
+
+PHASE 12: NEXT STEPS
+
+keep readers learning after the tutorial.
+
+
+continue learning
+
+suggest what to learn next:
+
+  next steps:
+  ----------
+
+  [ ] add more features
+      - task comments
+      - file attachments
+      - task assignments
+      - notifications
+
+  [ ] improve the api
+      - pagination for large datasets
+      - filtering and sorting
+      - full-text search
+      - rate limiting
+
+  [ ] harden the application
+      - add comprehensive logging
+      - implement caching with redis
+      - set up monitoring
+      - add ci/cd pipeline
+
+  [ ] related tutorials
+      - building a frontend for your api
+      - advanced authentication with oauth
+      - websocket real-time updates
+      - microservices architecture
+
+
+resources
+
+link to further learning:
+
+  official documentation:
+    - fastapi docs: https://fastapi.tiangolo.com
+    - sqlalchemy docs: https://docs.sqlalchemy.org
+    - pytest docs: https://docs.pytest.org
+
+  related tutorials:
+    - building a graphql api with fastapi
+    - docker and docker compose deep dive
+    - testing strategies for python apis
+
+  community:
+    - fastapi discord server
+    - r/fastapi on reddit
+    - stack overflow tag: fastapi
+
+
+PHASE 13: TUTORIAL QUALITY CHECKLIST
+
+
+before publishing, verify:
+
+content:
+  [ ] title is clear and action-oriented
+  [ ] introduction explains value
+  [ ] prerequisites are explicit
+  [ ] objectives are measurable
+  [ ] scope is well-defined
+
+code:
+  [ ] all code examples are tested
+  [ ] code follows best practices
+  [ ] code is properly formatted
+  [ ] file paths are clear
+  [ ] copy-paste works
+
+structure:
+  [ ] logical flow from start to finish
+  [ ] each step builds on previous
+  [ ] checkpoints to verify progress
+  [ ] troubleshooting for common issues
+
+verification:
+  [ ] each section has verification step
+  [ ] expected outputs are shown
+  [ ] errors are explained
+  [ ] solutions are provided
+
+accessibility:
+  [ ] language is clear and direct
+  [ ] jargon is explained
+  [ ] examples are relatable
+  [ ] multiple learning styles supported
+
+completeness:
+  [ ] tutorial can be completed in stated time
+  [ ] no steps are skipped
+  [ ] all commands are provided
+  [ ] all files are shown
+
+
+PHASE 14: TUTORIAL WRITING RULES (STRICT MODE)
+
+
+while this skill is active, these rules are MANDATORY:
+
+  [1] TEST EVERY CODE EXAMPLE
+      if you haven't run it, don't include it
+      broken examples destroy trust
+
+  [2] START WITH WORKING CODE
+      the first step must produce something that works
+      immediate success builds confidence
+
+  [3] VERIFY EACH STEP
+      after every step, show how to verify it works
+      readers should know if they're on track
+
+  [4] PROVIDE SOLUTIONS
+      for every problem you identify, provide a solution
+      never leave readers stuck
+
+  [5] BE EXPLICIT ABOUT PREREQUISITES
+      list exactly what readers need before starting
+      don't assume knowledge
+
+  [6] USE CONCRETE EXAMPLES
+      build something real, not abstract
+      task api is better than "example api"
+
+  [7] PROGRESSIVE COMPLEXITY
+      start simple, add complexity gradually
+      no sudden jumps in difficulty
+
+  [8] CHECKPOINTS AFTER EACH SECTION
+      readers must be able to verify their progress
+      provide git commits or verification commands
+
+  [9] INCLUDE TROUBLESHOOTING
+      anticipate common mistakes
+      provide solutions
+
+  [10] WRITE FOR ONE PERSON
+      define your audience persona
+      write specifically for them
+      don't try to please everyone
+
+
+PHASE 15: TUTORIAL TEMPLATES
+
+
+quick tutorial template (15-30 min)
+
+  title: [verb] [noun] in [timeframe]
+  subtitle: [what you'll accomplish]
+
+  in this tutorial, you'll [specific outcome].
+
+  prerequisites:
+    - [requirement 1]
+    - [requirement 2]
+
+  step 1: [first thing to do]
+  [setup/initial work]
+
+  step 2: [second thing]
+  [core functionality]
+
+  step 3: [third thing]
+  [finishing touches]
+
+  summary:
+  you now have [what was built].
+  next: [what to do next]
+
+
+medium tutorial template (1-2 hours)
+
+  title: [verb] [complete project]
+  subtitle: [description] | [time]
+
+  what you'll build:
+  [project description with features]
+
+  what you'll learn:
+  - [learning objective 1]
+  - [learning objective 2]
+  - [learning objective 3]
+
+  prerequisites:
+  [detailed prerequisites with setup instructions]
+
+  part 1: setup
+  [environment setup]
+
+  part 2: basics
+  [core functionality]
+
+  part 3: features
+  [main features]
+
+  part 4: polish
+  [refinement and testing]
+
+  part 5: deploy
+  [deployment steps]
+
+  what's next:
+  [continuation options]
+
+
+long tutorial template (half-day)
+
+  title: [comprehensive project]
+  subtitle: a complete guide to [topic]
+
+  about this tutorial:
+  [full overview with time estimates]
+
+  part 1: foundation (1 hour)
+  [fundamental concepts and setup]
+
+  part 2: core (2 hours)
+  [main implementation]
+
+  part 3: advanced (1.5 hours)
+  [advanced features]
+
+  part 4: production (1 hour)
+  [deployment and monitoring]
+
+  summary and next steps
+
+
+PHASE 16: MEASURING TUTORIAL SUCCESS
+
+
+metrics to track
+
+  quantitative:
+    - completion rate
+    - time to complete
+    - errors encountered
+    - questions asked
+
+  qualitative:
+    - reader confidence
+    - understanding of concepts
+    - satisfaction with result
+    - likelihood to recommend
+
+
+feedback collection
+
+add feedback prompts:
+
+  how did this tutorial go?
+  -------------------------
+  [ ] great! i learned a lot
+  [ ] good, but i got stuck a few times
+  [ ] confusing, needs improvement
+
+  what was confusing?
+  ___________________
+  [text area for feedback]
+
+  what would make this better?
+  ____________________________
+  [text area for suggestions]
+
+
+iterate based on feedback
+
+track common sticking points:
+
+  if many readers fail at step 5:
+    - break step 5 into smaller steps
+    - add more explanation
+    - add verification checkpoints
+
+  if many readers skip a section:
+    - maybe it's not needed
+    - make it optional
+    - move to separate tutorial
+
+
+FINAL REMINDERS
+
+
+tutorials are for learning
+
+the goal isn't just to complete the tutorial.
+the goal is to learn the concepts.
+focus on understanding, not just following steps.
+
+
+build confidence
+
+each step should increase confidence.
+early wins create momentum.
+verifiable progress creates trust.
+
+
+empathize with the reader
+
+remember when you were learning.
+what confused you?
+  explain that.
+what helped you understand?
+  include that.
+
+the reader is smart but inexperienced.
+write for them.
+
+
+when in doubt
+
+add a verification step.
+if the reader doesn't know if they succeeded,
+they'll lose confidence.
+show them how to check their work.
+
+now go teach someone something new.