Polish project documentation and repository metadata

.env.example

@@ -1,14 +1,15 @@
 # Git-Up server environment.
-# Copy to .env (or export these in your shell) — nothing here is required;
-# the app runs fully without any of these set.
+# Copy to .env or export these variables in your shell. server.js loads .env
+# automatically and never overrides variables that are already exported.
+# Nothing here is required; the app runs without any values set.
 
-# Port the HTTP server listens on (server.js). Defaults to 3000.
+# Port the HTTP server listens on. Defaults to 3000.
 PORT=3000
 
 # GitHub personal access token. Optional. Raises the GitHub API rate limit
-# (60 req/h unauthenticated) and enables Discussions scanning for the
-# failure-first analysis. Needs no scopes for public repositories.
-# Example: GITHUB_TOKEN=ghp_yourTokenHere
+# (60 requests/hour unauthenticated) and enables Discussions scanning for the
+# failure-first analysis. Use a token scoped only for the repositories you need.
+# Leave blank unless you understand the trust boundary.
 GITHUB_TOKEN=
 
 # E2B sandbox id. Optional — only used to print the correct preview URL

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,81 @@
+name: Bug report
+description: Report a reproducible Git-Up problem
+title: "Bug: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please redact tokens, passwords, private hostnames, and customer data before sharing logs.
+  - type: input
+    id: analyzed-repo
+    attributes:
+      label: Repository URL analyzed
+      description: Public GitHub URL that triggered the issue, if applicable.
+      placeholder: https://github.com/owner/repo
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Analyze flow
+        - Failure recovery
+        - Install contract or health score
+        - Path graph or generated script
+        - Browser UI or accessibility
+        - Server startup or deployment
+        - Documentation
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: List the smallest set of actions that reproduces the problem.
+      placeholder: |
+        1. Run `npm start`
+        2. Open http://localhost:3000
+        3. Analyze ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include redacted terminal/browser output when useful.
+    validations:
+      required: true
+  - type: input
+    id: node
+    attributes:
+      label: Node.js version
+      placeholder: v22.22.3
+  - type: dropdown
+    id: github-token
+    attributes:
+      label: Was GITHUB_TOKEN configured?
+      options:
+        - "No"
+        - "Yes"
+        - "Unsure"
+  - type: dropdown
+    id: ai-provider
+    attributes:
+      label: Was an AI provider configured?
+      options:
+        - "No"
+        - "Yes"
+        - "Unsure"
+  - type: textarea
+    id: checks
+    attributes:
+      label: Checks already run
+      placeholder: |
+        npm test → pass/fail
+        npm run smoke → pass/fail

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security policy
+    url: https://github.com/coderdoctor97/Git-up/security/policy
+    about: Read the private-reporting guidance before posting secrets, private URLs, or exploit details.

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,31 @@
+name: Documentation issue
+description: Report stale commands, unclear setup, broken links, or missing asset attribution
+title: "Docs: "
+labels: [documentation]
+body:
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Documentation area
+      options:
+        - README quick start or usage
+        - API reference
+        - Configuration or environment variables
+        - Architecture docs
+        - Asset attribution
+        - Contributing or security docs
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is wrong or missing?
+      description: Quote the stale command, broken link, or unclear section when possible.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence or suggested fix
+      description: Include the command output or link target you checked.

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## Summary
+
+- 
+
+## Verification
+
+- [ ] `npm ci`
+- [ ] `npm test`
+- [ ] `npm run smoke`
+- [ ] Manual browser check when UI changed
+
+## Risk and follow-up
+
+- New environment variables, permissions, network calls, or assets:
+- User-visible behavior changes:
+- Known limitations / follow-up:
+
+## Documentation
+
+- [ ] README or docs updated when commands, API responses, assets, or behavior changed
+- [ ] `docs/ASSETS.md` updated for added/replaced visual assets
+- [ ] No secrets, private URLs, or unredacted logs included

.nvmrc

@@ -0,0 +1 @@
+22

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Git-Up does not currently publish tagged releases. This changelog records notable repository-level changes until formal release notes are adopted.
+
+## Unreleased
+
+- Rebuilt project documentation around the verified Node/vanilla-JS implementation and current scripts.
+- Added a local smoke-test script for server startup, `/api/health`, the app shell, and key local assets.
+- Added project metadata (`repository`, `bugs`, `homepage`, `engines`, and explicit `UNLICENSED` package state).
+- Replaced the remote Oreo Lottie dependency with a local original SVG mascot.
+- Removed browser-side CDN scripts from the default page shell.
+- Added asset attribution, architecture, contributing, security, issue-template, and pull-request guidance.
+- Improved GitHub network/TLS error messages and corrected raw GitHub file URL construction.
+
+## 2.0.0
+
+- Current application version in `package.json` and `/api/health`.
+- Provides living install paths, failure-first analysis, multi-path install graph, install contracts, zero-context clone modes, and repository health scoring.

CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to Git-Up
+
+Thanks for helping make repository setup less painful. Git-Up is intentionally small: a Node HTTP server, vanilla browser modules, local assets, and offline tests.
+
+## Before you start
+
+1. Use Node.js 20 or newer. Node 22 is the preferred local version in `.nvmrc`.
+2. Install from a clean checkout:
+
+   ```bash
+   npm ci
+   ```
+
+3. Run the checks once before editing:
+
+   ```bash
+   npm test
+   npm run smoke
+   ```
+
+## Development loop
+
+```bash
+npm start
+```
+
+Open `http://localhost:3000`. The app can analyze public GitHub repositories without any AI provider. Set `GITHUB_TOKEN` only when you need higher GitHub API limits or Discussions scanning.
+
+## Project conventions
+
+- Keep the runtime dependency-free unless a dependency is clearly worth the long-term maintenance cost.
+- Keep command generation and path composition in `public/path-engine.js` so the browser, server, and generated install script agree.
+- Preserve the distinction between **reported** failures from GitHub threads and **inferred** findings from repository files.
+- Keep AI optional. A failing provider must fall back to deterministic local analysis or recovery.
+- Do not add remote README/app visuals unless their source, creator, license, and attribution are verified in `docs/ASSETS.md`.
+- Do not commit secrets, real tokens, private logs, or screenshots containing user data.
+
+## Tests to run
+
+| Change | Minimum checks |
+| --- | --- |
+| Server route, static asset route, startup behavior | `npm run smoke` plus relevant manual curl check |
+| Path composition, health, contract, failure scan, recovery | `npm test` |
+| Browser rendering, session state, Oreo chat UI | `npm test` |
+| Documentation-only change | Link/path check and `npm test` if commands or API examples changed |
+
+`npm run check` runs `npm test` and `npm run smoke` together.
+
+## Pull request checklist
+
+Before opening a pull request, include:
+
+- What changed and why.
+- The commands you ran and their actual result.
+- Screenshots or notes for UI changes when a browser check is possible.
+- Any new environment variables, permissions, network calls, or asset licenses.
+- Known limitations or follow-up work.
+
+## Reporting bugs
+
+Please include:
+
+- The repository URL you analyzed.
+- Your Node version (`node --version`).
+- Whether `GITHUB_TOKEN` or an AI provider was configured. Do not paste token values.
+- The step that failed and the smallest redacted terminal output that reproduces the issue.
+- Browser and operating system if the issue is UI-related.