Add project documentation (#4)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Report a problem with Deckless on your Linux desktop
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the problem clearly.
+
+## Environment
+
+- Distribution:
+- Desktop environment or window manager:
+- Display server: X11 or Wayland
+- Steam package source:
+- `gamescope` installed:
+- `gamemode` installed:
+
+## What happened
+
+Describe the observed behavior.
+
+## What you expected
+
+Describe the expected behavior.
+
+## Reproduction steps
+
+1.
+2.
+3.
+
+## Relevant configuration
+
+Share any relevant `deckless.env` or proxy configuration with secrets removed.
+
+## Extra notes
+
+Add logs, screenshots, or extra context here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Suggest an improvement for Deckless
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+Describe the workflow or feature you want.
+
+## Problem
+
+What user problem does this solve?
+
+## Proposed direction
+
+Describe the approach you have in mind, if any.
+
+## Alternatives considered
+
+List any alternatives or workarounds you tried.
+
+## Extra notes
+
+Add compatibility notes, links, or examples here.

.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+
+- describe the user-facing change
+
+## Testing
+
+- `bash -n install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge`
+- `shellcheck install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge`
+
+## Notes
+
+- mention any rollback, compatibility, or documentation impact

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is inspired by Keep a Changelog, and the project follows semantic versioning once tagged releases begin.
+
+## [0.1.0] - 2026-03-28
+
+### Added
+
+- A user-space Steam launcher that preserves the official client while splitting proxy policy between Steam web content and game traffic.
+- A runtime-managed `steamwebhelper` wrapper that removes forced GPU disable flags and restores the original Steam wrapper after exit.
+- Optional Big Picture launch integration for `gamescope`, `gamemode`, and `mangoapp`.
+- An i3 Big Picture bridge that hands fullscreen to launched games and restores it when they exit.
+- XDG-friendly install and uninstall scripts.
+- Example proxy and runtime configuration files.
+- Architecture and i3 integration documentation.
+- GitHub Actions validation for shell syntax and ShellCheck.
+
+[0.1.0]: https://github.com/m1ngsama/deckless/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Thanks for contributing to Deckless.
+
+## Project scope
+
+Deckless exists to improve the real desktop Linux Steam experience without forking or replacing the official Steam package.
+
+Changes are a good fit when they:
+
+- keep the official Steam client as the source of truth
+- stay auditable and small
+- solve real Linux desktop friction around Steam, Big Picture, controllers, graphics, audio, or proxy policy
+- improve installation, rollback, and documentation
+
+Changes are a poor fit when they:
+
+- require patching `/usr/bin/steam`
+- permanently rewrite Steam runtime files at rest
+- add large background services for problems that can be solved with small scripts
+
+## Development setup
+
+Required local tools:
+
+- `bash`
+- `jq`
+- `shellcheck`
+
+Optional for runtime testing:
+
+- `steam`
+- `gamescope`
+- `gamemode`
+- `i3`
+
+## Before opening a pull request
+
+Run:
+
+```bash
+bash -n install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge
+shellcheck install.sh uninstall.sh bin/deckless-steam bin/deckless-bigpicture bin/deckless-i3-bigpicture-bridge
+```
+
+If your change affects runtime behavior, include a short note about how you tested it.
+
+## Pull request guidelines
+
+- Keep pull requests focused.
+- Explain the user problem first, then the implementation.
+- Mention rollback or compatibility impact when you change install behavior.
+- Update documentation when you add or rename config variables.
+- Add a changelog entry only when preparing a tagged release.
+
+## Issues
+
+Please use the issue templates when possible:
+
+- bug reports for regressions or environment-specific failures
+- feature requests for new workflows or platform support
+
+## Code style
+
+- Prefer POSIX-adjacent shell where practical, but Bash is allowed.
+- Keep comments short and only where the behavior is not obvious.
+- Favor straightforward scripts over clever compactness.

README.md

@@ -136,6 +136,9 @@ Other X11 desktop environments may still benefit from the proxy split and Big Pi
 
 - [Architecture notes](docs/architecture.md)
 - [i3 integration](docs/i3.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
 
 ## License
 

docs/troubleshooting.md

@@ -0,0 +1,67 @@
+# Troubleshooting
+
+## Steam web pages still do not load
+
+Check the proxy file Deckless is reading:
+
+1. `DECKLESS_PROXY_ENV`
+2. `~/.config/deckless/proxy-env.sh`
+3. `~/.config/network/proxy-env.sh`
+4. inherited shell proxy variables
+
+Things to verify:
+
+- the proxy URL includes a scheme such as `http://` or `socks5h://`
+- local addresses are included in `no_proxy`
+- the proxy itself is reachable outside Steam
+
+## Games are using the proxy when they should be direct
+
+Deckless clears standard proxy environment variables before starting Steam. If a game still uses a proxy, the most likely causes are:
+
+- the game has its own proxy setting
+- a system-wide transparent proxy is in place
+- another launcher is injecting environment variables after Deckless starts Steam
+
+## Big Picture still falls back to software rendering
+
+Confirm that your system has working graphics userspace outside Steam first. Deckless only removes some Steam-side blockers; it cannot fix a broken driver stack.
+
+Useful checks:
+
+- `command -v gamescope`
+- `glxinfo -B`
+- `vulkaninfo --summary`
+
+Also check whether your system exposes one of these paths:
+
+- `/run/host/usr/lib/gbm`
+- `/usr/lib/gbm`
+- `/run/host/usr/share/glvnd/egl_vendor.d`
+- `/usr/share/glvnd/egl_vendor.d`
+
+## Big Picture launches but the game does not take fullscreen on i3
+
+The i3 bridge depends on:
+
+- `i3-msg`
+- `jq`
+- an i3 session that processes XDG autostart entries, or a manual bridge start
+
+You can start it manually with:
+
+```bash
+/usr/bin/bash ~/.local/share/deckless/bin/deckless-i3-bigpicture-bridge
+```
+
+If the game first opens a launcher window, that launcher may briefly take the fullscreen seat before the actual game window appears.
+
+## I want to go back to plain Steam
+
+Run:
+
+```bash
+./uninstall.sh
+```
+
+Deckless restores previously backed up local launchers and desktop entries when they existed at first install.