docs: add contributor guide, issue templates, and BOS quick start

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Report a problem in BOS documentation, workflow, or future implementation
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the bug clearly and briefly.
+
+## Current behavior
+
+What happens today?
+
+## Expected behavior
+
+What should happen instead?
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Additional context
+
+Include screenshots, logs, links, or notes if they help explain the issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest a new BOS capability, workflow, or documentation improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What gap, pain point, or opportunity does this request address?
+
+## Proposed improvement
+
+Describe the feature, documentation update, or workflow improvement you want to
+see.
+
+## Expected benefit
+
+Explain how this would help contributors, maintainers, or end users.
+
+## Notes
+
+Add examples, references, screenshots, or related issues if available.

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to BOS
+
+Thank you for helping shape BOS. This repository is still in an early,
+documentation-first stage, so thoughtful planning, issue refinement, and clear
+pull requests are just as valuable as code.
+
+## Before You Start
+
+- Check the open issues to avoid duplicating work.
+- If no issue exists, open one that explains the problem, the proposed
+  improvement, and the expected benefit.
+- Keep each pull request focused on one feature, fix, or documentation task.
+
+## Local Setup
+
+There is no application build pipeline in this repository yet. For now, the
+main setup steps are:
+
+```bash
+git clone https://github.com/bos-com/BOS.git
+cd BOS
+```
+
+Use a Markdown-friendly editor and preview your documentation changes before
+submitting them.
+
+## Branch Naming
+
+Use descriptive branch names that match the type of work being done:
+
+- `docs/<short-topic>` for documentation improvements
+- `feat/<short-topic>` for new features or scaffolding
+- `fix/<short-topic>` for bug fixes
+- `chore/<short-topic>` for maintenance tasks
+
+Examples:
+
+- `docs/readme-quick-start`
+- `feat/service-layout`
+- `fix/broken-links`
+
+## Pull Request Expectations
+
+Each pull request should:
+
+- reference the related issue number,
+- explain the problem being solved,
+- summarize the change,
+- describe how you verified it, and
+- note any follow-up work that remains.
+
+If your change affects documentation or contributor workflow, include before and
+after context so reviewers can quickly understand the improvement.
+
+## Documentation Standards
+
+- Prefer clear, direct language over placeholders.
+- Keep setup instructions honest to the current repository state.
+- Do not describe commands or services that do not yet exist in the repo.
+- Use consistent Markdown headings and code fences.
+
+## Reporting Issues
+
+When opening an issue, include:
+
+- a short, specific title,
+- the current problem or gap,
+- the proposed improvement,
+- why it matters, and
+- any relevant screenshots, logs, or links.
+
+Starter issue templates are available in `.github/ISSUE_TEMPLATE/`.
+
+## Review Checklist
+
+Before opening a pull request, make sure:
+
+- the change is scoped to the issue,
+- file names and headings are consistent,
+- links and commands are correct,
+- documentation reflects the real repository state, and
+- the PR description includes verification notes.

README.md

@@ -1,2 +1,90 @@
 # BOS
-BOS (Bugema Operating System) the internet OS! Free, Open Source, Self hostable
+
+BOS (Bugema Operating System) is a community-driven, self-hostable "internet
+OS" focused on simplifying web services for campus and community use.
+
+## Project Overview
+
+BOS is intended to become a practical foundation for shared digital services
+that schools, student communities, and local organisations can host for
+themselves. The project emphasizes simple deployment, open collaboration, and a
+workflow that helps new contributors learn by building in public.
+
+This repository is currently documentation-first. It captures the product
+direction, contribution workflow, and starter conventions for future modules.
+There is not yet a packaged installer or a runnable BOS application in this
+repository.
+
+## Goals
+
+- Provide a lightweight, open platform for hosting shared services.
+- Encourage contributions from students and community developers.
+- Keep deployments simple and self-hostable.
+- Establish a clear open-source workflow before the codebase expands.
+
+## Planned Scope
+
+The long-term BOS platform is expected to support:
+
+- campus and community web services,
+- reusable admin and collaboration tools,
+- self-hosted deployment patterns, and
+- documentation that helps new contributors onboard quickly.
+
+## Repository Contents
+
+| Path | Purpose |
+| --- | --- |
+| `README.md` | High-level project overview and onboarding notes |
+| `CONTRIBUTING.md` | Contribution workflow, branch naming, and PR guidance |
+| `LICENSE` | Repository license |
+| `.github/ISSUE_TEMPLATE/` | Starter issue templates for bugs and feature requests |
+
+## Quick Start
+
+Because BOS is still in a documentation-first phase, the quickest way to get
+started is to contribute to the project structure and planning materials.
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/bos-com/BOS.git
+   cd BOS
+   ```
+
+2. Review the current project direction in this README and the contribution
+   expectations in `CONTRIBUTING.md`.
+3. Choose an existing issue or open a new one describing the gap you want to
+   address.
+4. Create a focused branch, make your change, and open a pull request.
+
+## Local Requirements
+
+At the current project stage, contributors only need a lightweight toolchain:
+
+- Git for version control
+- A GitHub account for issues and pull requests
+- A text editor or IDE for Markdown and future code changes
+- Optional: Markdown preview support to validate documentation updates
+
+## Contributor Workflow
+
+- Start from a clear issue or documented improvement.
+- Keep changes scoped to one concern where possible.
+- Document assumptions when the repository does not yet contain runnable code.
+- Use pull requests to explain what problem was solved and how it was verified.
+
+Detailed conventions are documented in `CONTRIBUTING.md`.
+
+## Roadmap
+
+Near-term repository improvements include:
+
+- expanding architecture notes,
+- documenting expected service modules,
+- defining local development standards, and
+- introducing starter implementation scaffolding for BOS components.
+
+## License
+
+This project is available under the terms described in [`LICENSE`](LICENSE).