From f8d5dbf9dc758f826a6e8c0140be1f07d091d6b5 Mon Sep 17 00:00:00 2001
From: Michael Freeman <mfreeman451@gmail.com>
Date: Sun, 26 Oct 2025 21:50:14 -0500
Subject: [PATCH] addign dev docs

---
 guided/.tool-versions      |   2 +
 guided/CONTRIBUTING.md     | 368 +++++++++++++++++++++++++
 guided/README.md           | 231 +++++++++++++++-
 guided/docs/DEVELOPMENT.md | 536 +++++++++++++++++++++++++++++++++++++
 4 files changed, 1125 insertions(+), 12 deletions(-)
 create mode 100644 guided/.tool-versions
 create mode 100644 guided/CONTRIBUTING.md
 create mode 100644 guided/docs/DEVELOPMENT.md

diff --git a/guided/.tool-versions b/guided/.tool-versions
new file mode 100644
index 0000000..1962ca1
--- /dev/null
+++ b/guided/.tool-versions
@@ -0,0 +1,2 @@
+erlang 28.1.1
+elixir 1.19.1-otp-28
diff --git a/guided/CONTRIBUTING.md b/guided/CONTRIBUTING.md
new file mode 100644
index 0000000..daba157
--- /dev/null
+++ b/guided/CONTRIBUTING.md
@@ -0,0 +1,368 @@
+# Contributing to Guided.dev
+
+Thank you for your interest in contributing to Guided.dev! We're building the missing link between AI coding assistants and best-practice software development, and we'd love your help.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+- [Documentation](#documentation)
+- [Community](#community)
+
+## Code of Conduct
+
+This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please be respectful, inclusive, and considerate in all interactions.
+
+## Getting Started
+
+### Understanding the Project
+
+Before contributing, familiarize yourself with:
+
+1. **The Vision**: Read [GitHub Issue #1](https://github.com/your-org/guided/issues/1) for the complete PRD
+2. **The Implementation Plan**: See [docs/implementation_plan.md](docs/implementation_plan.md)
+3. **Current Progress**: Check [SETUP_COMPLETE.md](SETUP_COMPLETE.md) for Phase 0 completion status
+
+### Finding Something to Work On
+
+- Check the [Issues page](https://github.com/your-org/guided/issues)
+- Look for `good-first-issue` labels for beginner-friendly tasks
+- Look for `help-wanted` labels for areas where we need help
+- Check the project board for Phase 1 and Phase 2 tasks
+
+## Development Setup
+
+### Quick Setup
+
+We provide an automated setup script:
+
+```bash
+./scripts/dev_setup.sh
+```
+
+### Manual Setup
+
+For detailed manual setup instructions, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+
+## How to Contribute
+
+### Types of Contributions
+
+We welcome various types of contributions:
+
+1. **Code Contributions**
+   - New features (aligned with the implementation plan)
+   - Bug fixes
+   - Performance improvements
+   - Refactoring
+
+2. **Knowledge Graph Contributions**
+   - Adding new technologies
+   - Adding security vulnerabilities
+   - Adding best practices and secure coding patterns
+   - Adding deployment patterns
+
+3. **Documentation**
+   - Improving setup guides
+   - Adding code comments
+   - Writing tutorials
+   - Fixing typos
+
+4. **Testing**
+   - Writing tests for existing features
+   - Improving test coverage
+   - Testing edge cases
+
+5. **Design & UX**
+   - UI/UX improvements for the admin interface (Phase 1)
+   - Accessibility improvements
+
+### Reporting Bugs
+
+When reporting bugs, please include:
+
+- **Description**: Clear description of the issue
+- **Steps to Reproduce**: Detailed steps to reproduce the behavior
+- **Expected Behavior**: What you expected to happen
+- **Actual Behavior**: What actually happened
+- **Environment**: OS, Elixir version, Docker version
+- **Logs**: Relevant error messages or logs
+
+### Suggesting Features
+
+When suggesting features:
+
+- Check if the feature aligns with the [PRD](https://github.com/your-org/guided/issues/1)
+- Explain the use case and problem it solves
+- Consider how it fits into the phased implementation plan
+- Be open to discussion and feedback
+
+## Pull Request Process
+
+### Before You Start
+
+1. **Check for existing work**: Search issues and PRs to avoid duplication
+2. **Create or comment on an issue**: Discuss your proposed changes
+3. **Fork the repository**: Create your own fork to work in
+
+### Working on Your Contribution
+
+1. **Create a branch**: Use descriptive branch names
+   ```bash
+   git checkout -b feature/add-nodejs-knowledge
+   git checkout -b fix/graph-query-bug
+   git checkout -b docs/improve-setup-guide
+   ```
+
+2. **Make your changes**:
+   - Write clean, readable code
+   - Follow the coding standards (see below)
+   - Add or update tests
+   - Update documentation if needed
+
+3. **Test your changes**:
+   ```bash
+   mix test
+   mix format --check-formatted
+   mix precommit
+   ```
+
+4. **Commit your changes**:
+   - Write clear commit messages
+   - Reference related issues (e.g., "Fixes #123")
+   ```bash
+   git commit -m "Add Node.js to knowledge graph
+
+   - Add Node.js as a Technology node
+   - Add common Node.js vulnerabilities
+   - Add security best practices
+   - Update tests
+
+   Fixes #123"
+   ```
+
+### Submitting a Pull Request
+
+1. **Push to your fork**:
+   ```bash
+   git push origin feature/add-nodejs-knowledge
+   ```
+
+2. **Create a Pull Request** on GitHub with:
+   - Clear title describing the change
+   - Description of what changed and why
+   - Reference to related issues
+   - Screenshots (if UI changes)
+   - Checklist of completed items
+
+3. **PR Template** (we'll add this to `.github/PULL_REQUEST_TEMPLATE.md`):
+   ```markdown
+   ## Description
+   Brief description of changes
+
+   ## Type of Change
+   - [ ] Bug fix
+   - [ ] New feature
+   - [ ] Breaking change
+   - [ ] Documentation update
+   - [ ] Knowledge graph update
+
+   ## Related Issues
+   Fixes #(issue number)
+
+   ## Testing
+   - [ ] Tests pass (`mix test`)
+   - [ ] Pre-commit checks pass (`mix precommit`)
+   - [ ] Manual testing completed
+
+   ## Documentation
+   - [ ] Documentation updated (if needed)
+   - [ ] Code comments added (if needed)
+   ```
+
+4. **Respond to feedback**: Be receptive to code review comments
+
+### After Your PR is Merged
+
+- Delete your branch (optional)
+- Pull the latest changes from main
+- Celebrate! You've contributed to Guided.dev 🎉
+
+## Coding Standards
+
+### Elixir Style Guide
+
+We follow the [Elixir Style Guide](https://github.com/christopheradams/elixir_style_guide) with a few additions:
+
+1. **Formatting**: Always run `mix format` before committing
+   ```bash
+   mix format
+   ```
+
+2. **Documentation**: Add `@moduledoc` and `@doc` to all public modules and functions
+   ```elixir
+   defmodule Guided.NewModule do
+     @moduledoc """
+     Brief description of what this module does.
+     """
+
+     @doc """
+     Brief description of what this function does.
+
+     ## Examples
+
+         iex> NewModule.function_name(arg)
+         {:ok, result}
+     """
+     def function_name(arg) do
+       # implementation
+     end
+   end
+   ```
+
+3. **Naming Conventions**:
+   - Use `snake_case` for functions and variables
+   - Use `CamelCase` for modules
+   - Use descriptive names
+
+4. **Pattern Matching**: Use pattern matching for clarity
+   ```elixir
+   # Good
+   def process({:ok, result}), do: result
+   def process({:error, reason}), do: handle_error(reason)
+
+   # Less ideal
+   def process(result) do
+     case result do
+       {:ok, value} -> value
+       {:error, reason} -> handle_error(reason)
+     end
+   end
+   ```
+
+5. **Pipes**: Use the pipe operator for function chains
+   ```elixir
+   # Good
+   data
+   |> transform()
+   |> validate()
+   |> save()
+
+   # Less ideal
+   save(validate(transform(data)))
+   ```
+
+### Graph Database Conventions
+
+When working with the knowledge graph:
+
+1. **Node Labels**: Use singular nouns in PascalCase
+   - `Technology`, `Vulnerability`, `BestPractice`
+
+2. **Relationship Types**: Use SCREAMING_SNAKE_CASE
+   - `RECOMMENDED_FOR`, `HAS_VULNERABILITY`, `MITIGATED_BY`
+
+3. **Properties**: Use `snake_case` for property names
+   - `name`, `severity`, `owasp_rank`
+
+4. **Cypher Queries**: Format for readability
+   ```elixir
+   query = """
+   MATCH (t:Technology {name: $tech_name})
+         -[:HAS_VULNERABILITY]->(v:Vulnerability)
+         -[:MITIGATED_BY]->(sc:SecurityControl)
+   RETURN t.name, v.name, sc.name
+   ORDER BY v.severity DESC
+   """
+   ```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+mix test
+
+# Run a specific test file
+mix test test/guided/graph_test.exs
+
+# Run tests with coverage
+mix test --cover
+```
+
+### Writing Tests
+
+1. **Test file naming**: `test/path/to/module_test.exs`
+2. **Describe blocks**: Group related tests
+   ```elixir
+   defmodule Guided.GraphTest do
+     use Guided.DataCase
+
+     describe "create_node/2" do
+       test "creates a node with valid attributes" do
+         assert {:ok, _} = Graph.create_node("Technology", %{name: "Test"})
+       end
+
+       test "returns error with invalid attributes" do
+         assert {:error, _} = Graph.create_node("Technology", %{})
+       end
+     end
+   end
+   ```
+
+3. **Test coverage**: Aim for >80% coverage on new code
+4. **Edge cases**: Test error conditions and edge cases
+
+## Documentation
+
+### Types of Documentation
+
+1. **Code Documentation**: Add `@doc` to public functions
+2. **README**: Keep the main README up to date
+3. **Development Guide**: Update `docs/DEVELOPMENT.md` for setup changes
+4. **Inline Comments**: Explain complex logic
+
+### Documentation Standards
+
+- Use proper grammar and punctuation
+- Be concise but complete
+- Include examples where helpful
+- Keep documentation in sync with code
+
+## Community
+
+### Getting Help
+
+- **Questions**: Open a [Discussion](https://github.com/your-org/guided/discussions)
+- **Bugs**: Open an [Issue](https://github.com/your-org/guided/issues)
+- **Chat**: [Join our community chat] (if available)
+
+### Staying Updated
+
+- Watch the repository for updates
+- Follow the project roadmap
+- Participate in discussions
+
+## Recognition
+
+We value all contributions! Contributors will be:
+
+- Listed in a CONTRIBUTORS.md file
+- Acknowledged in release notes
+- Given credit in documentation they've written
+
+## Questions?
+
+If you have questions about contributing, please:
+
+1. Check the [Development Guide](docs/DEVELOPMENT.md)
+2. Search existing [Issues](https://github.com/your-org/guided/issues) and [Discussions](https://github.com/your-org/guided/discussions)
+3. Open a new Discussion if you can't find an answer
+
+Thank you for contributing to Guided.dev! Together we're building a better, more secure development ecosystem. 🚀
diff --git a/guided/README.md b/guided/README.md
index 2ca2be4..f9db25f 100644
--- a/guided/README.md
+++ b/guided/README.md
@@ -1,18 +1,225 @@
-# Guided
+# Guided.dev
 
-To start your Phoenix server:
+> A Protocol and Service for Building Great and Secure Software with AI Agents
 
-* Run `mix setup` to install and setup dependencies
-* Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
+Guided.dev provides the missing link between AI coding assistants and best-practice software development: a curated knowledge graph of secure coding patterns, vulnerabilities, and architectural guidance, accessible via a standardized protocol.
 
-Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
+## What is Guided.dev?
 
-Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).
+Guided.dev consists of two key innovations:
 
-## Learn more
+1. **A Curated Knowledge Graph**: A security-first knowledge base built on PostgreSQL with Apache AGE, containing:
+   - Technologies and frameworks
+   - Security vulnerabilities (OWASP Top 10)
+   - Best practices and secure coding patterns
+   - Deployment strategies
+   - Architectural guidance
 
-* Official website: https://www.phoenixframework.org/
-* Guides: https://hexdocs.pm/phoenix/overview.html
-* Docs: https://hexdocs.pm/phoenix
-* Forum: https://elixirforum.com/c/phoenix-forum
-* Source: https://github.com/phoenixframework/phoenix
+2. **The AGENTS.md Protocol**: A machine-readable specification that tells AI agents how to discover and interact with our guidance service, enabling structured, secure, and expert-informed development.
+
+## Current Status
+
+We're currently in **Phase 0** (Foundation & Setup) - **Complete** ✓
+
+- ✓ PostgreSQL with Apache AGE graph database
+- ✓ Graph query interface (`Guided.Graph`)
+- ✓ Initial knowledge base (24 nodes, 24 relationships)
+- ✓ Custom mix tasks for setup and seeding
+
+**Next Up**: Phase 1 - Admin CRUD Interface with Phoenix LiveView
+
+## Quick Start
+
+### Prerequisites
+
+- Erlang/OTP 28+
+- Elixir 1.19.1+
+- Docker
+
+### Setup
+
+```bash
+# 1. Install dependencies (if using asdf)
+asdf install
+
+# 2. Start PostgreSQL with Apache AGE
+docker run \
+  --name age \
+  -p 5455:5432 \
+  -e POSTGRES_USER=postgresUser \
+  -e POSTGRES_PASSWORD=postgresPW \
+  -e POSTGRES_DB=postgresDB \
+  -d \
+  apache/age
+
+# 3. Setup the application
+mix setup
+
+# 4. Setup and seed the graph database
+mix graph.setup
+mix graph.seed
+
+# 5. Start the Phoenix server
+mix phx.server
+```
+
+Visit [`localhost:4000`](http://localhost:4000) from your browser.
+
+## Project Vision
+
+### The Problem
+
+LLMs are powerful code generators but they operate in a vacuum. They often produce code that is functional but naive in its architecture, security, and scalability. There's no standardized way for AI agents to discover and consume curated best-practice knowledge.
+
+### The Solution
+
+**Guided.dev** provides:
+- A **trusted source** of security-first, opinionated guidance
+- A **clear protocol** (AGENTS.md) for AI agents to consume this guidance
+- A **graph-based knowledge model** for complex relationships between technologies, vulnerabilities, and mitigations
+
+### Example Use Case
+
+An AI agent building a Python web app:
+1. Discovers the project's `AGENTS.md` file
+2. Queries guided.dev's MCP server for tech stack recommendations
+3. Receives guidance on Streamlit + SQLite with security advisories
+4. Queries for secure coding patterns specific to those technologies
+5. Generates code using parameterized queries and proper input validation
+
+## Tech Stack
+
+- **Backend**: Elixir / Phoenix Framework
+- **Database**: PostgreSQL with Apache AGE extension (graph database)
+- **Frontend**: Phoenix LiveView (planned for Phase 1)
+- **Query Language**: openCypher
+
+## Features
+
+### Current (Phase 0)
+
+- ✓ Graph database with Apache AGE
+- ✓ openCypher query interface
+- ✓ Initial knowledge base covering:
+  - Python, Streamlit, SQLite, FastAPI
+  - OWASP Top 10 vulnerabilities
+  - Security controls and mitigations
+  - Best practices and deployment patterns
+
+### Planned
+
+**Phase 1** (Admin Interface):
+- LiveView-based admin CRUD interface
+- Node and relationship management
+- Graph visualization
+
+**Phase 2** (MCP Server):
+- Public-facing MCP API
+- Three core endpoints:
+  - `tech_stack_recommendation`
+  - `secure_coding_pattern`
+  - `deployment_guidance`
+
+## Development
+
+For detailed setup instructions, see [**docs/DEVELOPMENT.md**](docs/DEVELOPMENT.md).
+
+### Quick Commands
+
+```bash
+# Run tests
+mix test
+
+# Format code
+mix format
+
+# Full pre-commit check (compile, format, test)
+mix precommit
+
+# Reset database and graph
+mix ecto.reset
+mix graph.setup
+mix graph.seed
+
+# Start Phoenix server
+mix phx.server
+
+# Start with IEx (interactive Elixir)
+iex -S mix phx.server
+```
+
+### Testing the Graph
+
+```elixir
+# In IEx
+iex> Guided.Graph.query("MATCH (t:Technology) RETURN t.name")
+{:ok, [["Python"], ["Streamlit"], ["SQLite"], ["FastAPI"]]}
+
+iex> Guided.Graph.query("""
+  MATCH (t:Technology {name: 'Streamlit'})-[:HAS_VULNERABILITY]->(v:Vulnerability)
+  RETURN v.name, v.severity
+  """)
+{:ok, [["Cross-Site Scripting (XSS)", "high"], ["Path Traversal", "high"]]}
+```
+
+## Contributing
+
+We welcome contributors! To get started:
+
+1. Read the [Development Setup Guide](docs/DEVELOPMENT.md)
+2. Check out [GitHub Issue #1](https://github.com/your-org/guided/issues/1) for the full PRD
+3. Review [docs/implementation_plan.md](docs/implementation_plan.md) for the roadmap
+4. Look for issues labeled `good-first-issue`
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes and add tests
+4. Run `mix precommit` to ensure quality
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to your branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## Documentation
+
+- [Development Setup](docs/DEVELOPMENT.md) - Complete setup guide
+- [Implementation Plan](docs/implementation_plan.md) - Phased roadmap
+- [Phase 0 Completion](SETUP_COMPLETE.md) - Current progress
+- [AGENTS.md Specification](AGENTS.md) - The protocol spec
+- [Security Policy](SECURITY.md) - Security guidelines
+
+## Architecture
+
+```
+guided/
+├── lib/
+│   ├── guided/
+│   │   ├── graph.ex           # Graph database interface
+│   │   └── repo.ex            # Ecto repository
+│   ├── guided_web/            # Phoenix web interface
+│   └── mix/tasks/             # Custom mix tasks
+├── priv/repo/                 # Database migrations
+├── config/                    # Configuration files
+└── docs/                      # Documentation
+```
+
+## Learn More
+
+- **Phoenix Framework**: https://www.phoenixframework.org/
+- **Apache AGE**: https://age.apache.org/
+- **openCypher**: https://opencypher.org/
+- **Model Context Protocol**: https://modelcontextprotocol.io/
+
+## License
+
+[License information to be added]
+
+## Contact
+
+- **Issues**: [GitHub Issues](https://github.com/your-org/guided/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/your-org/guided/discussions)
+
+---
+
+Built with ❤️ by the Guided.dev team
diff --git a/guided/docs/DEVELOPMENT.md b/guided/docs/DEVELOPMENT.md
new file mode 100644
index 0000000..9318bda
--- /dev/null
+++ b/guided/docs/DEVELOPMENT.md
@@ -0,0 +1,536 @@
+# Development Setup Guide
+
+Welcome to guided.dev! This guide will help you get your development environment up and running.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Detailed Setup](#detailed-setup)
+- [Database Setup](#database-setup)
+- [Running the Application](#running-the-application)
+- [Common Tasks](#common-tasks)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+### Required Software
+
+- **Erlang/OTP 28** or later
+- **Elixir 1.19.1** or later
+- **Docker** (for PostgreSQL with Apache AGE)
+- **Git**
+
+### Recommended Tools
+
+- **asdf** - Version manager for Erlang and Elixir (recommended)
+- **Docker Desktop** or **Docker Engine**
+
+## Quick Start
+
+If you're already familiar with Elixir/Phoenix development:
+
+```bash
+# 1. Clone and enter the repository
+git clone https://github.com/your-org/guided.git
+cd guided
+
+# 2. Install Erlang and Elixir (if using asdf)
+asdf install
+
+# 3. Start PostgreSQL with Apache AGE
+docker run \
+  --name age \
+  -p 5455:5432 \
+  -e POSTGRES_USER=postgresUser \
+  -e POSTGRES_PASSWORD=postgresPW \
+  -e POSTGRES_DB=postgresDB \
+  -d \
+  apache/age
+
+# 4. Install dependencies and setup
+mix setup
+
+# 5. Setup the graph database
+mix graph.setup
+mix graph.seed
+
+# 6. Start the Phoenix server
+mix phx.server
+```
+
+Visit [`localhost:4000`](http://localhost:4000) in your browser!
+
+## Detailed Setup
+
+### 1. Install Erlang and Elixir
+
+#### Using asdf (Recommended)
+
+asdf is a version manager that allows you to manage multiple runtime versions easily.
+
+1. **Install asdf** (if not already installed):
+
+   ```bash
+   # macOS (using Homebrew)
+   brew install asdf
+
+   # Linux (using Git)
+   git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.13.1
+   ```
+
+2. **Add asdf plugins for Erlang and Elixir**:
+
+   ```bash
+   asdf plugin add erlang
+   asdf plugin add elixir
+   ```
+
+3. **Install the required versions** (defined in `.tool-versions`):
+
+   ```bash
+   # From the project root directory
+   asdf install
+   ```
+
+#### Manual Installation
+
+If you prefer not to use asdf:
+
+- **macOS (using Homebrew)**:
+  ```bash
+  brew install erlang elixir
+  ```
+
+- **Ubuntu/Debian**:
+  ```bash
+  wget https://packages.erlang-solutions.com/erlang-solutions_2.0_all.deb
+  sudo dpkg -i erlang-solutions_2.0_all.deb
+  sudo apt-get update
+  sudo apt-get install esl-erlang elixir
+  ```
+
+Verify your installation:
+```bash
+elixir --version
+# Should show: Elixir 1.19.1 (compiled with Erlang/OTP 28)
+```
+
+### 2. Install Docker
+
+Docker is required to run PostgreSQL with the Apache AGE extension.
+
+- **macOS**: [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/)
+- **Linux**: [Docker Engine](https://docs.docker.com/engine/install/)
+- **Windows**: [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
+
+Verify Docker is installed:
+```bash
+docker --version
+```
+
+### 3. Clone the Repository
+
+```bash
+git clone https://github.com/your-org/guided.git
+cd guided
+```
+
+## Database Setup
+
+guided.dev uses PostgreSQL with the **Apache AGE** extension to provide native graph database capabilities alongside traditional relational data.
+
+### Start PostgreSQL with Apache AGE
+
+1. **Pull and run the Apache AGE Docker image**:
+
+   ```bash
+   docker run \
+     --name age \
+     -p 5455:5432 \
+     -e POSTGRES_USER=postgresUser \
+     -e POSTGRES_PASSWORD=postgresPW \
+     -e POSTGRES_DB=postgresDB \
+     -d \
+     apache/age
+   ```
+
+   **Port Note**: We use port `5455` (not the default `5432`) to avoid conflicts with any existing PostgreSQL installations.
+
+2. **Verify the container is running**:
+
+   ```bash
+   docker ps
+   ```
+
+   You should see the `age` container in the list.
+
+### Access the PostgreSQL Database
+
+To access the database directly using `psql`:
+
+```bash
+docker exec -it age psql -d postgresDB -U postgresUser
+```
+
+Once inside psql, you can verify AGE is installed:
+
+```sql
+SELECT * FROM pg_available_extensions WHERE name = 'age';
+\q  -- to exit
+```
+
+### Database Configuration
+
+The application is pre-configured to connect to the Docker database. Configuration is in `config/dev.exs`:
+
+- **Host**: `localhost`
+- **Port**: `5455`
+- **Database**: `postgresDB`
+- **User**: `postgresUser`
+- **Password**: `postgresPW`
+
+These can be overridden with environment variables if needed (see `.env.example`).
+
+## Running the Application
+
+### First-Time Setup
+
+1. **Install dependencies**:
+
+   ```bash
+   mix deps.get
+   ```
+
+2. **Create and migrate the database**:
+
+   ```bash
+   mix ecto.setup
+   ```
+
+3. **Setup the graph schema**:
+
+   ```bash
+   mix graph.setup
+   ```
+
+4. **Seed the knowledge graph**:
+
+   ```bash
+   mix graph.seed
+   ```
+
+   This populates the graph with initial data including:
+   - Technologies (Python, Streamlit, SQLite, FastAPI)
+   - Use cases (web apps, dashboards, APIs)
+   - Vulnerabilities (OWASP Top 10)
+   - Security controls and best practices
+   - Deployment patterns
+
+### Start the Development Server
+
+```bash
+mix phx.server
+```
+
+Or start it inside IEx (Elixir's interactive shell) for debugging:
+
+```bash
+iex -S mix phx.server
+```
+
+The application will be available at [`http://localhost:4000`](http://localhost:4000).
+
+### Verify Graph Database
+
+You can test the graph database from IEx:
+
+```elixir
+iex> Guided.Graph.query("MATCH (t:Technology) RETURN t.name LIMIT 5")
+{:ok, [["Python"], ["Streamlit"], ["SQLite"], ["FastAPI"]]}
+```
+
+## Common Tasks
+
+### Reset the Database
+
+To completely reset the database (drop, create, migrate, seed):
+
+```bash
+mix ecto.reset
+mix graph.setup
+mix graph.seed
+```
+
+### Run Tests
+
+```bash
+mix test
+```
+
+### Run the Full Pre-commit Check
+
+This runs compilation with warnings as errors, format checking, and tests:
+
+```bash
+mix precommit
+```
+
+### Format Code
+
+```bash
+mix format
+```
+
+### Update Dependencies
+
+```bash
+mix deps.get
+mix deps.update --all
+```
+
+### Compile Assets
+
+Frontend assets (CSS, JS) are built using esbuild and Tailwind:
+
+```bash
+mix assets.build
+```
+
+### Database Operations
+
+```bash
+# Create the database
+mix ecto.create
+
+# Run migrations
+mix ecto.migrate
+
+# Rollback the last migration
+mix ecto.rollback
+
+# Check migration status
+mix ecto.migrations
+```
+
+### Graph Database Operations
+
+```bash
+# Setup graph schema (verify graph is accessible)
+mix graph.setup
+
+# Seed the knowledge graph with initial data
+mix graph.seed
+
+# Reset the graph (clears and re-seeds)
+mix graph.seed  # This automatically clears existing data
+```
+
+## Troubleshooting
+
+### Docker Container Issues
+
+**Problem**: Docker container won't start or port is already in use.
+
+**Solution**:
+```bash
+# Check if port 5455 is in use
+lsof -i :5455
+
+# Stop and remove existing container
+docker stop age
+docker rm age
+
+# Start fresh
+docker run --name age -p 5455:5432 \
+  -e POSTGRES_USER=postgresUser \
+  -e POSTGRES_PASSWORD=postgresPW \
+  -e POSTGRES_DB=postgresDB \
+  -d apache/age
+```
+
+### Database Connection Errors
+
+**Problem**: Can't connect to the database.
+
+**Solution**:
+1. Verify Docker container is running: `docker ps`
+2. Check the logs: `docker logs age`
+3. Test connection manually:
+   ```bash
+   docker exec -it age psql -d postgresDB -U postgresUser
+   ```
+
+### Mix Setup Fails
+
+**Problem**: `mix setup` or `mix ecto.setup` fails.
+
+**Solution**:
+1. Ensure Docker container is running
+2. Try individual steps:
+   ```bash
+   mix deps.get
+   mix ecto.create
+   mix ecto.migrate
+   mix graph.setup
+   mix graph.seed
+   ```
+
+### AGE Extension Not Found
+
+**Problem**: Error about AGE extension not being available.
+
+**Solution**:
+1. Verify you're using the `apache/age` Docker image
+2. Check AGE is installed:
+   ```bash
+   docker exec -it age psql -d postgresDB -U postgresUser -c "SELECT * FROM pg_available_extensions WHERE name = 'age';"
+   ```
+
+### Port Already in Use
+
+**Problem**: Port 4000 (Phoenix) or 5455 (Postgres) is already in use.
+
+**Solution**:
+```bash
+# For Phoenix (port 4000)
+lsof -i :4000
+kill -9 <PID>
+
+# Or set a different port
+PORT=4001 mix phx.server
+
+# For Postgres (port 5455)
+docker stop age
+# Or change the port mapping in the docker run command
+```
+
+### Compilation Errors
+
+**Problem**: Compilation errors after pulling new code.
+
+**Solution**:
+```bash
+# Clean and recompile
+mix clean
+mix deps.clean --all
+mix deps.get
+mix compile
+```
+
+### Asset Build Failures
+
+**Problem**: CSS or JS assets not loading.
+
+**Solution**:
+```bash
+# Reinstall and rebuild assets
+mix assets.setup
+mix assets.build
+```
+
+## Docker Management
+
+### Useful Docker Commands
+
+```bash
+# List all containers
+docker ps -a
+
+# Stop the database container
+docker stop age
+
+# Start the existing container
+docker start age
+
+# Remove the container (data will be lost)
+docker rm age
+
+# View container logs
+docker logs age
+
+# Follow logs in real-time
+docker logs -f age
+
+# Execute a command in the running container
+docker exec -it age bash
+```
+
+### Persisting Data
+
+The current setup does not persist data between container restarts. For development, this is usually fine since you can re-seed quickly.
+
+To persist data, add a volume mount:
+
+```bash
+docker run \
+  --name age \
+  -p 5455:5432 \
+  -e POSTGRES_USER=postgresUser \
+  -e POSTGRES_PASSWORD=postgresPW \
+  -e POSTGRES_DB=postgresDB \
+  -v guided_pgdata:/var/lib/postgresql/data \
+  -d \
+  apache/age
+```
+
+## Development Workflow
+
+1. **Create a new branch** for your feature or bug fix:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** and test locally:
+   ```bash
+   mix test
+   mix precommit
+   ```
+
+3. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "Description of changes"
+   ```
+
+4. **Push and create a pull request**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+## Additional Resources
+
+- [Phoenix Framework Documentation](https://hexdocs.pm/phoenix/overview.html)
+- [Elixir Documentation](https://elixir-lang.org/docs.html)
+- [Apache AGE Documentation](https://age.apache.org/age-manual/master/intro/overview.html)
+- [openCypher Query Language](https://opencypher.org/)
+- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
+
+## Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/your-org/guided/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/your-org/guided/discussions)
+- **PRD and Architecture**: See `docs/implementation_plan.md` and GitHub Issue #1
+
+## Project Structure
+
+```
+guided/
+├── assets/              # Frontend assets (CSS, JS)
+├── config/              # Application configuration
+├── docs/                # Documentation
+├── lib/
+│   ├── guided/          # Core application code
+│   │   ├── graph.ex    # Graph database interface
+│   │   └── repo.ex     # Ecto repository
+│   ├── guided_web/      # Web interface (controllers, views, LiveView)
+│   └── mix/
+│       └── tasks/       # Custom Mix tasks
+├── priv/
+│   ├── repo/           # Database migrations and seeds
+│   └── static/         # Static assets
+├── scripts/            # Utility scripts
+└── test/               # Tests
+```
+
+Happy coding!