Add contributing guide and project documentation (#8)

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contribute to Research Computing at Saint Louis University
+
+Welcome! This repository contains research software development at the Center for Digital Humanities, Saint Louis University. Below is how to get started.
+
+## What to work on
+
+Not sure where to start? The best signal is the issue tracker.
+
+- **`good first issue`** — meant for you. Clear scope, minimal setup, mentor available.
+- **`help wanted`** — open to anyone. May have trade-off decisions; feel free to ask.
+- **`bug`** — confirmed problems. Fix or reproduce → discuss → PR.
+- **`enhancement`** — feature requests. Propose a solution → get alignment → build it.
+
+No label? That's internal work-in-progress — open an issue first to coordinate.
+
+## Communication and etiquette
+
+- **Issues are for scoping, PRs are for code.** Discuss the problem in an issue. Implement the solution in a PR with a clear description.
+- **Reference upstream issues.** If your change addresses an issue, mention it (`Fixes #12`, `Closes #45`) so the link is automatic.
+- **Ask early, merge fast.** A short message ("I'm tackling this — aim for Friday") is worth more than a silent week of work.
+- **No rush.** This is research software, not a startup. Clear work beats fast work.
+
+## Getting started with a project
+
+Each project has its own setup. Pick one below:
+
+| Project | Focus | Status |
+|---------|-------|--------|
+| [TPEN3](/docs/tpen3.md) | New annotation platform | In development |
+| [tpen.tools](/docs/tpen-tools.md) | Utilities and services | Mature |
+| [Export TPEN](/docs/export-tpen.md) | Export small projects as static files | Mature |
+| [TPEN-IDE](/docs/tpen-ide.md) | Transcription and prompt workspace | Prototype |
+
+**Note:** the legacy T-PEN 2.8 platform is not yet documented here — coming soon.
+
+## Development conventions
+
+### Branching
+
+- Work on a named branch, not `main`.
+- Descriptive names help: `fix/login-broken`, `feat/new-tool`, `docs/readme-update`.
+- Open early — a draft PR is a great way to get feedback before it's finished.
+
+### Commits
+
+- Write messages that explain *why*, not just *what*.
+- Reference the issue when relevant: `Fix #23 — handle edge case in parser`.
+- Small, reviewable commits beat monoliths.
+
+### Pull requests
+
+- Target `main` unless told otherwise.
+- Describe what changed and why in the PR body.
+- Include screenshots for UI changes.
+- Request at least one reviewer.
+
+## Testing your changes
+
+- **Run it locally** before opening a PR — at minimum, start the app and hit the changed code path.
+- **Check the real URLs.** If the app is deployed, verify your branch build or a preview deploys correctly.
+- **Common breakage spots:** authentication flows, API endpoints, and anything that touches the TPEN 2.8 archive.
+
+## Ready to contribute?
+
+1. **Pick an issue** — `good first issue` is the friendliest start.
+2. **Fork and branch** — fork the repo, create a branch for your work.
+3. **Set up the project** — follow the guide linked above for your target project.
+4. **Open a PR** — describe your change, reference the issue, request a reviewer.
+
+Stuck? Open an issue or ask in an existing one — we're here to help.
+
+## License
+
+By contributing, you agree your contributions are licensed under the project's license (see each project page for details).

docs/export-tpen.md

@@ -0,0 +1,75 @@
+# Export TPEN — Static Project Export Tool
+
+**Repository:** [CenterForDigitalHumanities/ExportTPEN](https://github.com/CenterForDigitalHumanities/ExportTPEN)  
+**Live URL:** [export.t-pen.org](https://export.t-pen.org)  
+**Status:** Mature and actively used
+
+## What it is
+
+A simple web app that takes a TPEN 2.8 project and exports it as a static, standalone directory of files — HTML pages, JSON data, and images. The result can be hosted anywhere without a database.
+
+## Project structure
+
+```
+ExportTPEN/
+├── index.html          # Main app page (UI + logic)
+├── export.html         # Export status page
+├── js/                 # JavaScript modules
+├── css/                # Stylesheets
+└── images/             # Static assets
+```
+
+The entire app is a single `index.html` with inline JavaScript and CSS — simple to modify, no build step required.
+
+## Setup for development
+
+```bash
+# Clone the repository
+git clone https://github.com/CenterForDigitalHumanities/ExportTPEN.git
+cd ExportTPEN
+
+# Serve via any static file server
+npx http-server . -p 8080
+```
+
+Open `http://localhost:8080`. The app calls the TPEN 2.8 API, so you need network access to `t-pen.org`.
+
+## How it works
+
+1. User provides a TPEN 2.8 project ID or URL.
+2. The app fetches project data from the TPEN 2.8 API (pages, layers, annotations, images).
+3. It generates static files:
+   - `index.html` — viewable project page
+   - `project.json` — complete project data
+   - `page-N.json` — per-page annotation data
+   - `images/` — cached page images
+4. The result is downloadable as a ZIP or savable to a filesystem.
+
+## Common contribution areas
+
+- **Export format improvements** — better JSON structure, new file types
+- **UI polish** — clearer progress indicators, error messages
+- **Edge cases** — large projects, missing resources, special characters
+- **Documentation** — what the exported files look like and how to use them
+
+## Testing
+
+1. Start the local server
+2. Open the app in your browser
+3. Enter a real TPEN 2.8 project URL or ID
+4. Watch the export progress and inspect the output
+5. Open the generated `index.html` to verify it renders
+
+Use small projects for quick iteration. The live site at `export.t-pen.org` is always available for comparison.
+
+## Branching and PRs
+
+- Work on a named branch off `main`.
+- Open a PR targeting `main`.
+- Describe your change and what you tested.
+- Request a reviewer from the core team.
+
+## Contact
+
+- Repository owner: Center for Digital Humanities, Saint Louis University
+- See the [Contributing Guide](/CONTRIBUTING.md) for general contribution conventions.

docs/tpen-ide.md

@@ -0,0 +1,124 @@
+# TPEN-IDE — Transcription and Prompt Workspace
+
+**Repository:** [cubap/llm-ide](https://github.com/cubap/llm-ide)  (early prototype)
+**Live URL:** N/A (local file only)
+**Status:** Prototype — awaiting move into TPEN-3 monorepo
+
+## What it is
+
+TPEN-IDE is a browser-native, zero-install integrated workspace for TPEN
+transcription and prompt-driven annotation. It merges two workflows that are
+often siloed:
+
+- **Image-based transcription** — load a canvas image, draw lines, type text.
+- **Prompt-based generation** — compose LLM prompts, run them against a
+  provider, paste or auto-import the output as annotations.
+
+The result is a single environment where a transcription line can be drafted
+by hand or generated by a model, with the same review and export downstream.
+
+## Project structure
+
+```
+llm-ide/
+├── index.html  # SPA entry point — layout, tool panels, canvas
+├── style.css   # All presentation — card system, responsive layout
+└── README.md   # User-facing overview
+```
+
+There are no build steps, no bundler, and no dependencies. Opening `index.html`
+in a browser is sufficient.
+
+Key interaction patterns:
+
+- **Canvas-first UI.** The image canvas is the primary workspace; tools orbit
+  around it just like TPEN 2.8 and TPEN 3.
+- **Prompt-as-annotation.** A generated transcription line is stored the same
+  way as a typed one — the source (human vs model) is metadata, not a
+  structural difference.
+- **Zero setup.** No authentication, no API keys, no server required to open
+  the tool.
+
+## Setup for development
+
+```bash
+# Clone or download the files
+git clone https://github.com/cubap/llm-ide.git
+cd llm-ide
+
+# Open index.html in any browser
+open index.html          # macOS
+start index.html         # Windows
+xdg-open index.html      # Linux
+```
+
+No runtime, no package manager, no configuration needed.
+
+### Moving to TPEN-3 monorepo
+
+The long-term home for this workspace is `packages/tpen-ide` inside the
+[TPEN-3 monorepo](https://github.com/CenterForDigitalHumanities/TPEN-3). That
+move brings:
+
+- Shared TPEN components (CanvasViewer, AnnotationLayer, LineParser).
+- Shared services (Annotation, Project, Manifest).
+- TPEN authentication and project import flows.
+- Coordinated releases alongside TPEN 3.
+
+Until the monorepo is ready to absorb it, the standalone files are the
+source of truth.
+
+## Common contribution areas
+
+### Layout and Panels (`index.html`)
+
+- Canvas tool panel — line drawing, navigation, zoom.
+- Prompt tool panel — template selection, parameter input, run controls.
+- Annotation panel — review, edit, and export generated lines.
+- Responsive layout — split-panel behavior on narrow viewports.
+
+### Styling (`style.css`)
+
+- Card and panel visual hierarchy.
+- Canvas overlay rendering (lines, highlights, guides).
+- Dark mode or accessibility improvements.
+- Mobile and tablet breakpoints.
+
+### Cross-cutting
+
+- **Testing** — open in multiple browsers, check console, verify canvas
+  interactions.
+- **Documentation** — inline HTML comments, updated README.
+- **Monorepo migration** — identifying which TPEN-3 packages to pull in
+  and refactoring shared code out.
+
+## Useful files to know
+
+| File | Purpose |
+|------|---------|
+| `index.html` | SPA entry point — layout, tool panels, canvas viewer |
+| `style.css` | All presentation — card system, responsive layout |
+
+## Testing
+
+```bash
+# No test runner — open index.html and interact manually
+# Check:
+# - Canvas loads and responds to zoom/pan
+# - Tool panels open and close
+# - Prompt panel submits and displays output
+# - Console has no errors
+```
+
+## Branching and PRs
+
+- Work on a named branch off `main`.
+- Open a PR targeting `main`.
+- Describe your change: what changed, why, and how to test it.
+- Request a reviewer from the core team.
+
+## Contact
+
+- Repository author: cubap
+- Parent project: [TPEN-3](https://github.com/CenterForDigitalHumanities/TPEN-3)
+- See the [Contributing Guide](/CONTRIBUTING.md) for general contribution conventions.

docs/tpen-tools.md

@@ -0,0 +1,69 @@
+# tpen.tools — Utilities and Services
+
+**Repository:** [CenterForDigitalHumanities/tpen.tools](https://github.com/CenterForDigitalHumanities/tpen.tools)  
+**Live URL:** [tpen.tools](https://tpen.tools)  
+**Status:** Mature and actively used
+
+## What it is
+
+A collection of web-based tools for interacting with TPEN data — project management, annotation editing, image processing, and interoperability utilities. Each tool is a standalone page that can be embedded or opened directly.
+
+## Project structure
+
+```
+tpen.tools/
+├── index.html          # Landing page / tool directory
+├── tools/              # Individual tool pages
+│   ├── project/        # Project management tools
+│   ├── annotation/     # Annotation editing tools
+│   ├── image/          # Image processing utilities
+│   └── export/         # Data export helpers
+├── js/                 # Shared JavaScript modules
+├── css/                # Stylesheets
+└── images/             # Static assets
+```
+
+## Setup for development
+
+This is a static site — no build step or backend required.
+
+```bash
+# Clone the repository
+git clone https://github.com/CenterForDigitalHumanities/tpen.tools.git
+cd tpen.tools
+
+# Serve via any static file server
+npx http-server . -p 8080
+```
+
+Open `http://localhost:8080` in your browser. Most tools call the TPEN 2.8 API directly, so they work as-is — though some endpoints may require authentication.
+
+## Common contribution areas
+
+- **New tools** — add a page under `tools/` that solves a specific task
+- **Shared modules** — factor out common patterns into `js/` for reuse
+- **Tool improvements** — better UX, edge-case handling, accessibility
+- **Documentation** — each tool should describe its inputs, outputs, and limitations
+
+## Testing
+
+Tools are tested by opening them and exercising the core workflow:
+
+1. Start the local server (`npx http-server`)
+2. Open the tool page
+3. Perform the primary action (load a project, save an annotation, export data)
+4. Check the browser console for errors
+
+Some tools depend on the TPEN 2.8 API — make sure you can reach `t-pen.org` from your environment.
+
+## Branching and PRs
+
+- Work on a named branch off `main`.
+- Open a PR targeting `main`.
+- Describe your change and link the tool URL.
+- Request a reviewer from the core team.
+
+## Contact
+
+- Repository owner: Center for Digital Humanities, Saint Louis University
+- See the [Contributing Guide](/CONTRIBUTING.md) for general contribution conventions.