Open-source launch docs and acceptance test

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,52 @@
+---
+name: Bug report
+about: Report a problem with SourceDraft Studio, publishing, or configuration
+title: ""
+labels: bug
+assignees: ""
+---
+
+## SourceDraft version / commit
+
+<!-- e.g. v0.1.0 or git commit SHA -->
+
+## Environment
+
+- **OS:**
+- **Node version:** (`node -v`)
+- **pnpm version:** (`pnpm -v`)
+- **Browser:**
+
+## Configuration
+
+- **Adapter:** (`astro-mdx` or `markdown`)
+- **contentDir:**
+- **mediaDir:**
+- **publicMediaPath:** (if set)
+- **GitHub target:** owner/repo and branch (do not paste tokens)
+
+## What happened
+
+### Error message / logs
+
+```
+Paste relevant server or browser console output. Redact tokens and secrets.
+```
+
+### Expected behavior
+
+<!-- What you expected to happen -->
+
+### Actual behavior
+
+<!-- What happened instead -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Additional context
+
+<!-- Optional: screenshots (no secrets), related issues -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,35 @@
+---
+name: Feature request
+about: Suggest an improvement for SourceDraft core or adapters
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+<!-- What problem does this solve? Who is affected? -->
+
+## Proposed feature
+
+<!-- Describe the behavior you want. Keep it concrete. -->
+
+## Target user
+
+<!-- e.g. solo blogger, static-site developer, maintainer self-hosting Studio -->
+
+## Adapter / publisher affected
+
+<!-- e.g. astro-mdx, markdown, github-publisher, Studio UI only, none -->
+
+## Core vs plugin / future adapter
+
+<!-- Why should this live in SourceDraft core rather than a site-specific script, future adapter, or external tool? -->
+
+## Alternatives considered
+
+<!-- Optional: other approaches you thought about -->
+
+## Additional context
+
+<!-- Optional: links, sketches, related issues -->

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to SourceDraft are documented here. The project uses [Semantic Versioning](https://semver.org/) where practical.
+
+## v0.1.0
+
+First public open-source MVP for local/private Git-backed publishing.
+
+### Added
+
+- **Studio editor** for Markdown and MDX posts with universal article fields (title, slug, dates, category, tags, draft, body)
+- **Markdown and MDX publishing** via adapters (`astro-mdx`, `markdown`)
+- **GitHub publishing** through the Contents API (`@sourcedraft/github-publisher`)
+- **Existing post listing and editing** from configured `contentDir`
+- **Image uploads** to `mediaDir` (PNG, JPEG, GIF, WebP; 5 MB max)
+- **Configurable `publicMediaPath`** — separate repo write path from URL path inserted into posts
+- **Universal article validation** (`@sourcedraft/core`)
+- **Project configuration** via `sourcedraft.config.json` and `.env` overrides
+- **CI baseline** — build and unit tests on push/PR
+
+### Security (MVP)
+
+- Local/private **password auth** with server-side session cookies
+- GitHub token and admin password stay on the server only
+- Lightweight same-site protection on state-changing API routes
+
+**Warning:** MVP password auth is intended for local or private use. Do not expose Studio publicly without HTTPS, stronger auth, and deployment hardening.
+
+### Known limitations
+
+- GitHub Contents API only (no Git Trees API or content indexer yet)
+- In-memory sessions (lost when the API restarts)
+- No OAuth, user accounts, or hosted multi-tenant product
+- Large content folders may hit GitHub listing or file-size limits
+
+See [docs/project-status.md](docs/project-status.md) for current scope.

CONTRIBUTING.md

@@ -1,29 +1,79 @@
-# Contributing
+# Contributing to SourceDraft
 
-SourceDraft is early-stage. Prefer small, typed changes over large refactors.
+Thank you for helping improve SourceDraft. This project is an early open-source MVP for Git-backed Markdown and MDX publishing — not a hosted SaaS product.
 
-## Principles
+## Local setup
 
-- Universal article schema in `@sourcedraft/core`
-- Site-specific values in config files, not hardcoded in packages
-- No generic SaaS UI patterns, fake metrics, or placeholder screens
-- Secrets only in server code and `.env`
+Requirements:
 
-## Docs
+- Node.js 22+
+- pnpm 11+
 
-Update user-facing docs when behavior changes:
+```bash
+git clone https://github.com/bnz183/SourceDraft.git
+cd SourceDraft
+pnpm install
+
+cp sourcedraft.config.example.json sourcedraft.config.json
+cp .env.example .env
+```
+
+Edit `.env` with local values for development. **Do not commit `.env` or `.env.local`.**
+
+`GITHUB_TOKEN`, `GITHUB_OWNER`, `GITHUB_REPO`, and `SOURCEDRAFT_ADMIN_PASSWORD` are read only by the Studio server (`apps/studio/server`). They must never be added to client code, issue reports, or screenshots.
 
-- [README.md](README.md)
-- [docs/getting-started.md](docs/getting-started.md)
-- [docs/github-publishing.md](docs/github-publishing.md)
-- [docs/configuration.md](docs/configuration.md)
-- [docs/project-status.md](docs/project-status.md)
+## Branch workflow
 
-## Development
+1. Fork the repository (or create a branch if you have write access).
+2. Branch from `main` with a short descriptive name, for example `fix/post-list-error` or `docs/contributing`.
+3. Keep changes focused — avoid unrelated refactors.
+4. Open a pull request against `main` with a clear summary and test notes.
+
+## Commands
+
+From the repository root:
 
 ```bash
-pnpm install
-pnpm dev
+pnpm install    # install workspace dependencies
+pnpm build      # build all packages and Studio (including server TypeScript)
+pnpm test       # run unit tests
+pnpm dev        # start Studio UI + publish API locally
+```
+
+Optional:
+
+```bash
+pnpm lint       # lint workspace packages where configured
+pnpm check      # TypeScript check without emit
 ```
 
-Runs Studio and the publish API from the repo root.
+CI runs `pnpm install --frozen-lockfile`, `pnpm build`, and `pnpm test` on push and pull requests.
+
+## What to contribute
+
+Good first contributions:
+
+- Documentation fixes and clarity
+- Tests for pure helpers in `packages/*`
+- Clearer error messages (server-side)
+- Bug fixes with a small, focused diff
+
+Please avoid:
+
+- Hardcoding site-specific logic (QuBrite or any single publication)
+- Exposing secrets or tokens in browser code
+- Large refactors without an issue discussion first
+- Fake features, metrics, or placeholder UI
+
+## Reporting issues
+
+Use the GitHub issue templates:
+
+- [Bug report](.github/ISSUE_TEMPLATE/bug_report.md)
+- [Feature request](.github/ISSUE_TEMPLATE/feature_request.md)
+
+Do not paste live tokens, passwords, or private repository details in public issues.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

README.md

@@ -2,8 +2,16 @@
 
 SourceDraft is a free, open-source editor for Markdown and MDX blogs backed by GitHub. You write in the browser, upload images, check your metadata, preview the generated file, and publish into your site repository.
 
+**Project status:** SourceDraft is an early local/private MVP for Git-backed Markdown and MDX publishing. It is usable for solo writing and GitHub commits, but it is not a hosted CMS, multi-user product, or finished SaaS. See [docs/project-status.md](docs/project-status.md) and [CHANGELOG.md](CHANGELOG.md).
+
 SourceDraft began as an internal tool for [QuBrite.com](https://qubrite.com) and is published here for anyone running a similar static-site workflow. QuBrite is the origin story, not a dependency — you point SourceDraft at your own repository and config.
 
+## Screenshots
+
+Screenshots are not included in the repository yet. Expected images and capture instructions: [docs/screenshots.md](docs/screenshots.md).
+
+When added, they will live in `docs/assets/` (overview, editor preview, media upload, publish success).
+
 ## What is SourceDraft?
 
 SourceDraft is not WordPress and not a hosted website builder. It is a local **Studio** (editor) plus a small **publish API** that commits content and media files to GitHub.
@@ -80,7 +88,7 @@ Start Studio (UI + publish API):
 pnpm dev
 ```
 
-Sign in, open **New Article**, preview the output, publish. The file lands at `contentDir/<slug>.mdx` or `.md` depending on your adapter (default: `src/content/blog/`).
+Sign in, open **Write**, preview the output, publish. The file lands at `contentDir/<slug>.mdx` or `.md` depending on your adapter (default: `src/content/blog/`).
 
 Full walkthrough: [docs/getting-started.md](docs/getting-started.md)
 
@@ -92,7 +100,7 @@ If someone technical already installed SourceDraft and pointed it at your blog r
 2. The admin password they set in `.env`
 3. Your site’s category list (from `sourcedraft.config.json`)
 
-Then: sign in → **Overview** to open an existing post, or **New Article** → fill in title, description, date, category, tags, and body → upload images if needed → check the preview → **Publish to GitHub**. Your post appears as a file in the blog repo; the normal site build deploys it.
+Then: sign in → **Posts** to open an existing post, or **Write** → fill in title, description, date, category, tags, and body → upload images if needed → check the preview → **Publish to GitHub**. Your post appears as a file in the blog repo; the normal site build deploys it.
 
 You do not edit GitHub by hand or run terminal commands for each post. If publish is disabled, ask your technical contact to check `.env` (GitHub token and repo) and that Studio is running with `pnpm dev`.
 
@@ -122,6 +130,10 @@ Reference: [docs/configuration.md](docs/configuration.md)
 
 [examples/astro-blog/](examples/astro-blog/) is a **folder layout example** — not a runnable Astro site. It shows where files go, a sample published `.mdx`, and matching config. Read its README before copying paths into your own blog repo.
 
+## Contributing
+
+Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, commands, and security reminders.
+
 ## Documentation
 
 - [Getting started](docs/getting-started.md)
@@ -133,7 +145,10 @@ Reference: [docs/configuration.md](docs/configuration.md)
 - [Architecture](docs/architecture.md)
 - [Adapters](docs/adapters.md)
 - [Project status](docs/project-status.md)
+- [Manual acceptance test](docs/manual-acceptance-test.md)
 - [Security](docs/security.md)
+- [Screenshots guide](docs/screenshots.md)
+- [Changelog](CHANGELOG.md)
 
 ## License
 

docs/architecture.md

@@ -40,7 +40,7 @@ Studio (browser)
 Publish API (server)
     → listFiles / readFile (@sourcedraft/github-publisher)
     → parse frontmatter, validate (@sourcedraft/core)
-    → JSON for Overview and edit flow
+    → JSON for Posts list and edit flow
 ```
 
 ## Packages

docs/assets/README.md

@@ -0,0 +1,35 @@
+# docs/assets
+
+Static images for SourceDraft documentation (primarily README screenshots).
+
+## Naming
+
+Use lowercase kebab-case PNG files:
+
+- `studio-overview.png`
+- `editor-preview.png`
+- `media-upload.png`
+- `publish-success.png`
+
+Add new screenshots only when they reflect the current Studio UI.
+
+## Privacy and security
+
+Before committing an image, confirm it does **not** show:
+
+- GitHub tokens or personal access tokens
+- `.env` contents or `SOURCEDRAFT_ADMIN_PASSWORD`
+- Private repository names you do not want public (use a test repo or blur)
+- Personal email addresses, internal URLs, or unrelated proprietary content
+
+Studio Settings fields are read-only, but screenshots can still expose owner/repo names and folder paths. Use a dedicated test GitHub repository when possible.
+
+## Usage
+
+Reference images from the root README or docs with relative paths, for example:
+
+```markdown
+![Studio overview](docs/assets/studio-overview.png)
+```
+
+See [screenshots.md](../screenshots.md) for capture instructions.

docs/configuration.md

@@ -128,3 +128,5 @@ Secrets:
 ```
 .env only (never in sourcedraft.config.json)
 ```
+
+For local development and contributions, see [CONTRIBUTING.md](../CONTRIBUTING.md). Release history: [CHANGELOG.md](../CHANGELOG.md).

docs/getting-started.md

@@ -36,7 +36,7 @@ GITHUB_BRANCH=main
 
 | File | Holds |
 |------|--------|
-| `sourcedraft.config.json` | `contentDir`, `mediaDir`, categories, adapter |
+| `sourcedraft.config.json` | `contentDir`, `mediaDir`, `publicMediaPath`, categories, adapter |
 | `.env` | Password, GitHub token, repo owner/name |
 
 See [configuration.md](configuration.md) for the full split.
@@ -59,8 +59,8 @@ Sign in with `SOURCEDRAFT_ADMIN_PASSWORD`.
 
 ## 5. Write and publish
 
-1. **Overview** — see existing posts from GitHub; click **Edit**, or use **New Article**
-2. Fill in the form; upload images under **Hero image** if needed ([media.md](media.md))
+1. **Posts** — see existing posts from GitHub; click **Edit**, or open **Write** for a new post
+2. Fill in post details; upload a cover image if needed ([media.md](media.md))
 3. Check the Markdown or MDX preview and output path
 4. **Publish to GitHub**