Prepare OSS readiness package

Adds OSS documentation, setup guides, release checklist, issue backlog, security notes, CI workflow, templates, and README improvements for App Dev Planner public-readiness.

Author: marcomartinomarch2005

.env.example

@@ -0,0 +1,5 @@
+# Copy this file to .env.local for local development.
+# Do not commit .env.local or any real credentials.
+
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_ANON_KEY=

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,23 @@
+---
+name: Documentation
+about: Suggest a documentation improvement
+title: "docs: "
+labels: documentation
+assignees: ""
+---
+
+## Documentation area
+
+Which page, file, or section should be improved?
+
+## Problem
+
+What is unclear, missing, outdated, or hard to follow?
+
+## Suggested improvement
+
+Describe the change you would like to see.
+
+## Additional context
+
+Add links, screenshots, examples, or related issues if helpful.

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+      - main
+      - oss-readiness
+
+jobs:
+  build:
+    name: Lint and build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+        env:
+          NEXT_PUBLIC_SUPABASE_URL: https://example.supabase.co
+          NEXT_PUBLIC_SUPABASE_ANON_KEY: dummy-anon-key-for-ci

.gitignore

@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel

CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+App Dev Planner aims to be a respectful, practical, and welcoming project for people who want to improve app planning workflows.
+
+## Expected behavior
+
+- Be kind and professional.
+- Assume good intent, especially when discussing early ideas or incomplete work.
+- Give feedback that is specific, useful, and focused on the project.
+- Respect different experience levels, languages, backgrounds, and working styles.
+- Keep issues and pull requests constructive and on topic.
+
+## Unacceptable behavior
+
+- Harassment, insults, threats, or personal attacks.
+- Discriminatory language or behavior.
+- Publishing private information without permission.
+- Repeated off-topic comments or spam.
+- Any behavior that makes collaboration unsafe or hostile.
+
+## Reporting
+
+If you see behavior that violates this code of conduct, contact the project maintainer privately. The maintainer may remove comments, close issues, block users, or take other reasonable action to keep the project healthy.
+
+## Scope
+
+This code of conduct applies to project spaces including issues, pull requests, discussions, documentation, and related community channels.

README.md

@@ -1,53 +1,106 @@
 # App Dev Planner
 
-App Dev Planner is an open-source planning workspace for turning rough app ideas into structured technical specifications, implementation roadmaps, and exportable development briefs.
+App Dev Planner is an open-source planning workspace for turning rough app ideas into technical specs, roadmaps, and developer-ready briefs.
 
-The project is designed for solo developers, indie hackers, small teams, and AI-assisted builders who need a repeatable way to clarify product scope before writing code. Instead of starting with a blank document, App Dev Planner guides users through product, technical, and implementation questions, then converts the answers into a structured technical planning document.
+The project is currently an early MVP under active development. It is being prepared for a stronger public/open-source release posture, but it should still be treated as a work in progress.
 
-## Why this exists
+## Problem
 
-Many early-stage app ideas fail because the planning stage is scattered across chat logs, notes, docs, screenshots, and unfinished prompts. App Dev Planner aims to make that process more consistent by providing a focused workflow for:
+Early app ideas often live across chat logs, notes, screenshots, and unfinished documents. That makes it hard for builders to clarify scope, identify technical risks, and hand a project to a developer or AI coding agent with enough context.
 
-- defining the app concept and target users;
-- clarifying core features and MVP scope;
-- documenting authentication, data, UI, and architecture needs;
-- generating a technical development brief from guided answers;
-- exporting planning output for developers, AI coding agents, or project handoff.
+App Dev Planner provides a guided planning flow that turns product, technical, security, testing, deployment, and maintenance answers into a structured technical blueprint.
 
-## Current MVP scope
+## Target users
 
-The current MVP includes the foundation for:
+- Solo developers validating a new app idea before implementation.
+- Indie hackers turning product ideas into actionable build plans.
+- Freelancers collecting clearer client requirements.
+- Product-minded builders preparing developer-ready briefs.
+- Students or small teams documenting capstone, MVP, or internal-tool plans.
+- AI-assisted builders who want better prompts, specs, and handoff documents.
 
-- user authentication flow;
-- dashboard and project list;
-- new project creation with app type selection;
-- guided brainstorming across multiple planning sections;
-- autosaved planning answers;
-- generated technical documentation from user answers;
-- document preview;
-- HTML and Markdown export workflow;
-- project progress tracking and project detail actions;
-- landing page with product positioning.
+## What the app currently does
+
+Based on the current codebase, App Dev Planner includes:
+
+- A public landing page introducing the planning workflow.
+- Email/password registration and login through Supabase Auth.
+- A protected dashboard that lists the signed-in user's projects.
+- Project creation with app name, app type, description, and draft status.
+- A guided brainstorming flow with 12 sections and 55 questions.
+- Autosaved brainstorming answers stored in Supabase.
+- Project detail pages with progress tracking across answered questions.
+- Markdown technical blueprint generation from saved answers.
+- Preview of the generated technical blueprint.
+- Client-side export to visual HTML and Markdown.
+- PDF export guidance through browser print from the generated HTML.
+- Project deletion that removes related brainstorming answers and generated documents.
+
+## Current limitations
+
+- The app expects a Supabase project and compatible tables/policies to exist.
+- Database migrations are not yet included in the repository.
+- Automated tests are not yet present.
+- CI is limited to dependency install, lint, and build checks.
+- Screenshots, demo video, and hosted demo links still need to be added.
+- Some generated blueprint sections describe intended architecture and future capabilities, not all of which are implemented as app routes today.
 
 ## Tech stack
 
-- Next.js
-- React
+- Next.js 16 App Router
+- React 19
 - TypeScript
-- Tailwind CSS
-- Supabase
-- DOCX/document export utilities
+- Tailwind CSS 4
+- Supabase Auth and PostgreSQL
+- `@supabase/ssr` and `@supabase/supabase-js`
+- `file-saver` for browser downloads
+- `docx` dependency reserved for document export work
+- ESLint
+
+## Project structure
+
+```text
+app/
+  page.tsx                         Public landing page
+  (auth)/login/page.tsx            Login page
+  (auth)/register/page.tsx         Registration page
+  auth/logout/route.ts             Logout route
+  dashboard/page.tsx               Protected project dashboard
+  projects/new/page.tsx            Project creation
+  projects/[id]/page.tsx           Project detail and progress
+  projects/[id]/brainstorming/     Guided planning questions
+  projects/[id]/preview/           Generated blueprint preview
+  projects/[id]/export/            Export UI and client-side exporters
+lib/
+  supabase-browser.ts              Browser Supabase client
+  supabase-server.ts               Server Supabase client
+  supabase.ts                      Shared Supabase client
+proxy.ts                           Supabase session refresh and route protection
+```
 
-## Getting started
+## Local setup
 
-Clone the repository and install dependencies:
+Clone the repository:
 
 ```bash
 git clone https://github.com/marcomartinomarch2005/app-dev-planner.git
 cd app-dev-planner
+```
+
+Install dependencies:
+
+```bash
 npm install
 ```
 
+Create a local environment file:
+
+```bash
+cp .env.example .env.local
+```
+
+Fill in your local Supabase values in `.env.local`.
+
 Run the development server:
 
 ```bash
@@ -58,58 +111,86 @@ Open `http://localhost:3000` in your browser.
 
 ## Environment variables
 
-This project uses Supabase. Create a `.env.local` file and add the required Supabase values for your local environment.
+Only public Supabase browser values are required by the current app code:
 
 ```bash
-NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
-NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_ANON_KEY=
 ```
 
-Do not commit real API keys, database credentials, service-role keys, or private environment values.
+Use `.env.local` for real values. Do not commit `.env.local`, service-role keys, database passwords, or other private credentials.
 
-## Roadmap
+## Supabase setup notes
+
+The code currently reads and writes these tables:
+
+- `projects`
+- `brainstorming_answers`
+- `generated_documents`
+- `export_history`
+
+The app assumes authenticated users can only access their own project data. Before a public demo or production deployment, confirm Row Level Security policies, table constraints, and delete behavior in Supabase.
+
+See [docs/SUPABASE_SETUP.md](./docs/SUPABASE_SETUP.md) for setup notes, schema outline, and RLS reminders.
+
+## Screenshots and demo
+
+Screenshots and demo materials are still pending.
 
-Planned improvements include:
+Suggested additions before public launch:
 
-- stronger README screenshots and demo flow;
-- public demo deployment;
-- issue templates and pull request template;
-- richer document export options;
-- AI-assisted specification review;
-- implementation task generation;
-- project templates for SaaS, internal tools, content tools, and automation apps;
-- test coverage and CI workflow;
-- security hardening around auth and data access.
+- Landing page screenshot.
+- Dashboard screenshot with sample data.
+- Brainstorming flow screenshot.
+- Generated blueprint preview screenshot.
+- Exported HTML/Markdown sample.
+- Short demo video or hosted demo link.
 
-## How AI/Codex can help this project
+See [docs/screenshots/README.md](./docs/screenshots/README.md) for screenshot placement, naming, and privacy guidance.
 
-App Dev Planner is a strong candidate for AI-assisted maintenance because its core workflow is about structured planning, specification generation, and developer handoff. Codex/API support could help with:
+## Documentation
 
-- reviewing generated technical specifications;
-- creating implementation task lists from planning answers;
-- improving test coverage;
-- detecting gaps in app architecture documents;
-- maintaining documentation and examples;
-- improving contributor onboarding;
-- automating issue triage and release preparation.
+- [Supabase setup](./docs/SUPABASE_SETUP.md)
+- [Public release checklist](./docs/PUBLIC_RELEASE_CHECKLIST.md)
+- [Issue backlog drafts](./docs/ISSUE_BACKLOG.md)
+- [Screenshot guidance](./docs/screenshots/README.md)
+- [Open-source application notes](./docs/OPEN_SOURCE_APPLICATION_NOTES.md)
+
+## Roadmap
+
+See [ROADMAP.md](./ROADMAP.md) for the current public-readiness roadmap.
+
+Near-term themes include:
+
+- Public release readiness.
+- Documentation and demo assets.
+- Export improvements.
+- AI-assisted specification review.
+- Testing and CI.
+- Security hardening.
+- App planning templates.
 
 ## Contributing
 
-Contributions are welcome once the repository is made public. Please read `CONTRIBUTING.md` before opening an issue or pull request.
+Contributions are welcome once the repository is public. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening an issue or pull request.
 
 Good first contribution areas include:
 
-- improving documentation;
-- adding screenshots or demo walkthroughs;
-- refining question flows;
-- improving export formatting;
-- adding tests;
-- improving accessibility and UI clarity.
+- Improving setup documentation.
+- Adding screenshots or demo walkthroughs.
+- Refining planning questions.
+- Improving generated blueprint formatting.
+- Adding tests.
+- Improving accessibility and UI clarity.
 
 ## Security
 
-Please do not open public issues for sensitive security reports. See `SECURITY.md` for responsible disclosure guidance.
+Please do not open public issues for sensitive security reports. See [SECURITY.md](./SECURITY.md) for responsible disclosure guidance.
+
+## Code of conduct
+
+This project uses a concise contributor code of conduct. See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
 
 ## License
 
-This project is released under the MIT License. See `LICENSE` for details.
+This project is released under the MIT License. See [LICENSE](./LICENSE) for details.