Added comment system

CLAUDE.md

@@ -0,0 +1,218 @@
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## 5. Act as a Partner, Not a Tool
+
+**Use natural conversation. Start broad, go deep together.**
+
+In our work together:
+- Explain context and goals in natural, conversational language rather than just keywords.
+- Start broad for ideation, then we'll go deeper on specific ideas to avoid generic results.
+- Divide complex tasks into smaller, manageable, sequential prompts rather than one large, ambiguous request.
+- Surface tradeoffs and ask clarifying questions before committing to a direction.
+- Treat this as a collaborative partnership where we iterate and refine together.
+
+## 6. Act as a Teacher
+
+**Document the learning journey. Build a knowledge base as we go.**
+
+Throughout this project:
+- Explain *how* and *why* solutions work, not just what they do.
+- When you solve a problem or figure out a new approach, document the reasoning in comments or summary notes.
+- For complex code or architecture decisions, and for any new or updated source file, maintain a complete annotated reference copy in `references/` (e.g., `filename_annotated_cp.py`) that fully mirrors the production file rather than summarizing it.
+- Annotated reference copies must break down major sections with structural labels and decision explanations so they teach both what the code does and why it exists.
+- Keep annotated references in sync immediately whenever production code changes, and use the `references/` folder consistently so it remains a reliable long-term learning system for revisiting past decisions.
+- Surface patterns, gotchas, and lessons learned so future work builds on what we've already discovered.
+
+This isn't just about code—it's about building institutional knowledge that makes the next feature, bug fix, or refactor faster and more confident.
+
+## 7. Reference Documentation Governance
+
+**Each reference document must have one clear responsibility. Avoid overlap.**
+
+- Keep each reference focused on its purpose (for example: architecture, quickstart, testing, completion snapshot, conceptual notes).
+- Do not duplicate large sections across multiple reference files.
+- When overlap appears, keep the canonical content in one file and link to it from others.
+- Update reference documents continuously as development progresses, not in large delayed batches.
+- If a file is moved, update relative links so references remain navigable.
+- Prefer concise, maintainable reference docs over long repeated walkthroughs.
+
+## 8. Testing Code is Essential
+
+**Write reliable tests. Test often, test early.**
+
+Testing is how we ensure software works as intended and catches regressions.
+
+### Structure and Scope
+
+- **AAA Pattern (Arrange, Act, Assert)**: Set up test data, run the code, assert the result.
+- **One Thing Only**: Each unit test focuses on one tiny piece of functionality.
+- **Independent**: Tests run alone or in any order without relying on other tests.
+- **Isolate Dependencies**: Use mocks or stubs to isolate code from external factors (databases, APIs).
+
+### Testing Scenarios (What to Test)
+
+- **Positive Scenarios**: Test that code works with valid inputs.
+- **Negative Scenarios**: Test that code fails gracefully with invalid inputs (expected exceptions).
+- **Boundary Conditions**: Test edge cases (empty sets, max values, null inputs).
+- **One-to-Many Relationships**: Test cascade deletes, foreign key constraints, and relationship integrity.
+
+### Test Quality and Maintenance
+
+- **Fast & Reliable**: Tests must run quickly; avoid flaky tests that fail randomly.
+- **Descriptive Naming**: Name tests to explain what is being tested (e.g., `test_should_return_manufacturers_when_get_all_called`).
+- **Treat as Production Code**: Write clean, readable, maintainable test code.
+- **Avoid Logic in Tests**: Keep tests simple; no complex if/for loops in test bodies.
+
+### Workflow
+
+- **Test-Driven Development (TDD)**: Consider writing the test before the code to define the requirement.
+- **Automate Everything**: Run tests automatically on every build and check-in.
+- **Fix Immediately**: If a test fails, fix it immediately to maintain confidence in the suite.
+- **Test Often**: Write tests for each new feature, endpoint, and edge case as you implement.
+
+### File Organization
+
+- Place all tests in the `tests/` folder with clear labels.
+- Name test files following the pattern: `test_<module>.py` (e.g., `test_manufacturers.py`, `test_products.py`).
+- Create corresponding subdirectories: `tests/unit/`, `tests/integration/` as needed.
+- Use `__init__.py` in test folders to make them packages.
+
+### What Not to Test (Unit Testing)
+
+- Do not test constants, properties, or simple wrappers unless they contain complex logic.
+- Do not test private methods directly; test them through public methods.
+- Focus on testing functionality, edge cases, and behavior.
+
+---
+
+## 9. GitHub Issue and Sub-Issue Management
+
+**Keep the backlog clean. Promote checklist items to real sub-issues.**
+
+### Duplicate Detection and Cleanup
+
+When asked to audit or clean up GitHub issues:
+1. Collect all open issue titles across every page: navigate to `/issues?state=open&per_page=100&page=N` for each page until pagination ends.
+2. Build a map of `title → [issue numbers]` and flag any titles that appear more than once.
+3. **GitHub does not hard-delete issues.** Close the duplicate (higher number), keeping the lower-numbered original open.
+4. Report the closed issue number to the user so they can verify or hard-delete it manually if needed.
+
+### Converting Checklist Items to Real Sub-Issues
+
+When asked to convert checklist subtasks into actual GitHub sub-issues for an epic issue:
+
+1. Navigate to the epic issue page.
+2. Read all remaining checklist items: `page.evaluate(() => Array.from(document.querySelectorAll('[data-testid^="tasklist-item-"] input[type="checkbox"]')).map(cb => cb.getAttribute('aria-label')?.replace(' checklist item', '')))`.
+3. For each item, run this loop pattern:
+   ```js
+   // Hover to reveal the task options button
+   await page.getByRole('checkbox', { name: `${label} checklist item` }).first().hover();
+   await page.waitForTimeout(600);
+   // Click the task options button
+   await page.getByRole('button', { name: `Open ${label} task options` }).click();
+   await page.waitForTimeout(400);
+   // Convert to sub-issue
+   await page.getByRole('menuitem', { name: 'Convert to sub-issue' }).click();
+   await page.waitForTimeout(1500);
+   ```
+4. If a single item fails (menu timeout), reload the page, re-query the remaining checklist items, and retry only the ones still present as checkboxes.
+5. After all conversions, verify by re-checking that the checklist is empty: the `[data-testid^="tasklist-item-"]` query should return `[]`.
+
+### Best Practices
+
+- Process one epic at a time; reload the page between epics to get a clean DOM state.
+- Sub-issues already converted disappear from the checklist automatically — the same label will not be found twice.
+- After finishing all epics, scan all pages again for duplicates introduced during the batch conversion run.
+
+---
+
+## 10. Kanban Card and GitHub Project Automation Prompts
+
+When managing project tasks, always clarify user intent before acting:
+
+### Kanban Card Conversion Flow
+
+1. **Prompt:** "Would you like me to convert these checklist tasks to Kanban cards?"
+   - If yes: Convert each checklist item into a main issue (epic) and sub-issue cards as appropriate.
+   - If no: Do not create cards; ask if the user wants a summary or export instead.
+
+2. **Prompt:** "Would you like me to upload these cards directly to your GitHub repo?"
+   - If yes: Ask for the GitHub repository URL (e.g., `https://github.com/owner/repo`).
+   - If no: Offer to export the cards as markdown, CSV, or another format.
+
+3. **Prompt:** If the site is blocked by sign-in (e.g., GitHub login required):
+   - Explain the authentication barrier to the user.
+   - Walk the user through the manual sign-in process:
+     - Instruct them to open the site in their browser and sign in.
+     - After sign-in, return to the automation flow.
+   - If automation is not possible, offer a manual step-by-step guide for creating cards/issues.
+
+### Reference for Future Automation
+- Use this prompt sequence whenever converting tasks/checklists to Kanban or GitHub issues.
+- Always confirm before uploading or modifying a remote repository.
+- If blocked by authentication, pause and guide the user through sign-in, then resume.
+- Document any manual steps taken for traceability.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, clarifying questions come before implementation rather than after mistakes, our conversation feels natural and goal-oriented, the references folder is a trusted learning resource, and tests catch bugs before production.

CodeWalkthrough-Handout.md

@@ -0,0 +1,164 @@
+# CircusCircus Code Walkthrough Handout (1-Page)
+
+Use this sheet while reading the code together.
+
+## Goal
+
+By the end, everyone should be able to explain:
+
+- how the app starts,
+- how requests are handled,
+- how DB models connect,
+- how routes map to templates.
+
+## Read Order (Follow Exactly)
+
+1. config.py
+2. forum/__init__.py
+3. forum/app.py
+4. forum/models.py
+5. forum/routes.py
+6. templates in this order:
+   - layout.html
+   - header.html
+   - subforums.html
+   - subforum.html
+   - viewpost.html
+   - createpost.html
+   - login.html
+
+## What To Find In Each File
+
+## 1) config.py
+
+- SECRET_KEY
+- SQLALCHEMY_DATABASE_URI
+- FLASK_APP
+
+Ask:
+
+- Which values are dev-only?
+- Which should come from environment variables?
+
+## 2) forum/__init__.py
+
+- create_app()
+- blueprint registration
+- db.init_app(app)
+
+Ask:
+
+- Where is app-wide wiring done?
+- Where are routes attached?
+
+## 3) forum/app.py
+
+- app = create_app()
+- login manager and user_loader
+- seed logic: init_site() and add_subforum()
+- index route: /
+
+Ask:
+
+- Why is seed logic running at startup?
+- Should seeding be moved to a command?
+
+## 4) forum/models.py (4 Schemas)
+
+- User: auth fields + posts/comments relationships
+- Post: title/content/date + user/subforum foreign keys
+- Subforum: parent/child structure + posts
+- Comment: content/date + user/post foreign keys
+
+Also review:
+
+- valid_title(), valid_content()
+- generateLinkPath()
+
+Ask:
+
+- Are helpers in the best layer?
+- Is breadcrumb HTML generation in the right place?
+
+## 5) forum/routes.py (HTTP Handlers)
+
+Auth/account:
+
+- POST /action_login
+- GET /action_logout
+- POST /action_createaccount
+- GET /loginform
+
+Subforums/posts/comments:
+
+- GET /subforum
+- GET /addpost
+- POST /action_post
+- GET /viewpost
+- POST/GET /action_comment
+
+Ask:
+
+- Which routes mutate DB data?
+- Which routes require login?
+- Where is input validation done?
+
+## 6) Templates (Rendering Flow)
+
+Base:
+
+- layout.html wraps all pages
+- header.html shows auth state and site info
+
+Pages:
+
+- subforums.html (home list)
+- subforum.html (subforum + posts)
+- viewpost.html (single post + comments)
+- createpost.html (new post form)
+- login.html (login + register)
+
+Route map:
+
+- / -> subforums.html
+- /loginform -> login.html
+- /subforum -> subforum.html
+- /addpost -> createpost.html
+- /viewpost -> viewpost.html
+
+## One Full Request/Response Trace
+
+Example: GET /subforum?sub=1
+
+1. Browser sends HTTP request for /subforum?sub=1.
+2. Flask's WSGI loop receives it and matches route to subforum() in routes.py.
+3. Route runs SQLAlchemy queries:
+   - load selected subforum,
+   - load posts in that subforum,
+   - load child subforums.
+4. Route calls render_template("subforum.html", ...) with context data.
+5. Jinja2 renders subforum.html, which extends layout.html and includes header.html.
+6. Flask returns rendered HTML in HTTP response.
+7. Browser renders page and fetches static CSS.
+
+Black box vs your code:
+
+- Flask/WSGI black box: socket/request parsing, route dispatch internals, response transport.
+- Your code: handler logic, ORM queries, validation, template selection, context values.
+
+## 30-Minute Fast Agenda
+
+1. 0-5 min: config + factory
+2. 5-10 min: app.py startup + seed
+3. 10-18 min: models and relationships
+4. 18-25 min: routes and DB writes
+5. 25-30 min: templates and final Q&A
+
+## End-of-Session Check
+
+Each person should answer all 4:
+
+1. Where does the app get config values?
+2. Which route creates a post and where is validation?
+3. How does a comment connect to both user and post?
+4. Which template is the base wrapper for all pages?