ZurvanLinux · mshafiee · Jul 20, 2026 · Jul 20, 2026
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -0,0 +1,94 @@
+name: Lint (reusable)
+
+# Reusable lint workflow called by individual repos via:
+#   jobs:
+#     lint:
+#       uses: ZurvanLinux/.github/.github/workflows/lint.yml@main
+# Runs in the CALLER repo's context (it lints the caller's files).
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: shellcheck + yamllint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install linters
+        run: |
+          set -eux
+          sudo apt-get update
+          sudo apt-get install -y shellcheck yamllint
+
+      - name: shellcheck
+        run: |
+          set -e
+          # Discover shell scripts: *.sh, the live-build auto/ directory, and any
+          # file whose first line is a sh/bash/dash shebang.
+          files=$( {
+            find . -type f \( -name '*.sh' -o -path './auto/*' \) -not -path './.git/*' -not -path './node_modules/*';
+            grep -rIl --include='*' -E '^#![[:space:]]*/[^[:space:]]*/(env[[:space:]]+)?(sh|bash|dash)([[:space:]]|$)' . 2>/dev/null \
+              | grep -v -e '^./.git/' -e '^./node_modules/';
+          } | sort -u )
+          if [ -z "$files" ]; then
+            echo "No shell scripts found; skipping shellcheck."
+            exit 0
+          fi
+          echo "Linting:"; echo "$files"
+          # SC2312: "consider invoking grep without cat" is noise for scripts we own.
+          echo "$files" | xargs shellcheck --external-sources --format=gcc --exclude=SC2312
+
+      - name: yamllint
+        run: |
+          set -e
+          # Tolerant config tuned for GitHub Actions YAML (line length off; the
+          # workflow `on:` key would trip truthy, so check-keys is off).
+          files=$(find . -type f \( -name '*.yml' -o -name '*.yaml' \) \
+                  -not -path './.git/*' -not -path './node_modules/*')
+          if [ -z "$files" ]; then
+            echo "No YAML files found; skipping yamllint."
+            exit 0
+          fi
+          echo "Linting:"; echo "$files"
+          echo "$files" | xargs yamllint -d '{extends: default,
+            rules: {
+              line-length: disable,
+              document-start: disable,
+              indentation: disable,
+              comments: disable,
+              comments-indentation: disable,
+              truthy: {check-keys: false},
+              new-line-at-end-of-file: disable
+            }}'
+
+  astro:
+    name: astro check + build
+    runs-on: ubuntu-latest
+    # Only runs in repos that actually have an Astro config (e.g. website).
+    if: ${{ hashFiles('astro.config.mjs', 'astro.config.*', 'astro.config.ts') != '' }}
+    env:
+      ASTRO_TELEMETRY_DISABLED: '1'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: astro check
+        run: npm run check
+
+      - name: astro build
+        run: npm run build
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,67 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**conduct@zurvanlinux.org**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,72 @@
+# Contributing to Zurvan Linux
+
+نوشته‌های زیر را می‌توانید به فارسی یا انگلیسی بخوانید؛ مشارکت در هر دو زبان ممکن است. First: thank you for helping build a Persian-first Debian distribution.
+
+## Read the spec first
+
+The five documents in [`ZurvanLinux/ZurvanLinux`](https://github.com/ZurvanLinux/ZurvanLinux) are the source of truth:
+
+| Doc | Covers |
+|-----|--------|
+| `technical-spec-architecture.md` | Architecture, kernel/driver stack, desktop, Calamares |
+| `package-manifest.md` | Exact pre-installed apt/flatpak/codec/font packages |
+| `ui-ux-localization-plan.md` | Vazirmatn, RTL, ISIRI 9147 keyboard, Jalali |
+| `distribution-update-strategy.md` | ISO delivery, APT repo, GPG signing |
+| `testing-qa-checklist.md` | Release-validation checklist (the release gate) |
+
+Also read [`AGENTS.md`](https://github.com/ZurvanLinux/ZurvanLinux/blob/main/AGENTS.md) for the **hard constraints** (Debian 13 `amd64`-only in Phase 1, Plasma 6.7 Wayland-default, `contrib`/`non-free`/`non-free-firmware` on, Vazirmatn fontconfig, ISIRI 9147 + ZWNJ on `Shift+Space`, `Asia/Tehran` + Jalali). Do not deviate without opening a discussion issue first.
+
+## Where things live
+
+| Repo | What belongs here |
+|------|-------------------|
+| `ZurvanLinux` | Spec docs (prose changes only) |
+| `iso-builder` | `live-build` config + the ISO build pipeline |
+| `apt-repository` | `pool/` of `.deb`s + the publish/signing workflow |
+| `website` | Astro landing page |
+| `branding-assets` | Wallpapers, themes, icons |
+| `zurvan-dns-bypass` | The DNS-switcher source + packaging |
+| `welcome-app` | First-boot welcome assistant |
+| `.github` | This file, org templates, reusable lint workflow |
+
+## How to propose a change
+
+1. **Open an issue first** for anything beyond a trivial fix — especially anything that touches a spec doc or a hard constraint. Use the bug/feature templates.
+2. **Branch from `main`** using `feat/...`, `fix/...`, `docs/...`, or `chore/...`. Trunk-based; keep branches short-lived.
+3. **Open a pull request** against `main`. Fill in the PR template checklist. For Phase 1 (solo + AI agents) PRs are not hard-enforced but are the convention and the review record.
+4. **Keep diffs focused.** One logical change per PR. If you touch a hard constraint, call it out explicitly in the PR description.
+
+## Coding conventions
+
+- **Shell:** POSIX-friendly where possible (`sh`), `bash` only when needed. `set -eu`. Lint with `shellcheck` (the reusable `lint` workflow runs it).
+- **Workflows (YAML):** pin Actions to a major (`@v4`) or SHA; validate with `yamllint` (reusable `lint` workflow).
+- **Astro / TypeScript:** `astro check` must pass with 0 errors.
+- **No secrets in code.** Use repository / org secrets for credentials.
+- **Bilingual UX copy:** Persian is the source language; mirror in English via `src/i18n/ui.ts` on the website. Use ZWNJ (نیم‌فاصله) correctly in Persian text.
+
+## Lint locally
+
+The reusable workflow in this repo (`ZurvanLinux/.github/.github/workflows/lint.yml`) runs `shellcheck` + `yamllint` (+ an Astro build check on the website). To opt a repo in, add a tiny caller:
+
+```yaml
+# .github/workflows/lint.yml
+name: Lint
+on: { push: { branches: [main] }, pull_request: {} }
+jobs:
+  lint:
+    uses: ZurvanLinux/.github/.github/workflows/lint.yml@main
+```
+
+## Testing
+
+- **ISO:** changes to `iso-builder` should produce a green `build-iso.yml` run and boot to a login prompt in QEMU (see that repo's README).
+- **Website:** `npm run check` + `npm run build` must pass; verify RTL/LTR on both locales.
+- **APT repo:** `publish-repo.yml` must regenerate indices cleanly; signing requires the P0 secrets.
+
+## Licensing
+
+Each repository declares its own license in its `LICENSE` file. By contributing, you agree your contributions are licensed under that repository's license. The spec docs are CC-BY-SA-4.0; code is GPL-compatible per repo.
+
+## Questions?
+
+Open a `triage` issue, or start a discussion once Phase 1 ships Discussions (planned for Phase 5). For security matters, see [`SECURITY.md`](./SECURITY.md).
diff --git a/ISSUE_TEMPLATE/bug_report.yml b/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,53 @@
+name: 🐛 Bug report
+description: Report something that is broken or behaves incorrectly.
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug! \
+        می‌توانید این گزارش را به فارسی یا انگلیسی پر کنید. لطفاً تا حد امکان تصاویر یا خروجی ترمینال را ضمیمه کنید.
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component / repo
+      options:
+        - iso-builder (ISO build / live image)
+        - apt-repository
+        - website
+        - branding-assets
+        - zurvan-dns-bypass
+        - welcome-app
+        - ZurvanLinux (spec docs)
+        - other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: ISO / package version (if applicable)
+      placeholder: "e.g. v0.2.0-pre.3, or git commit SHA"
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug and what you expected instead.
+      placeholder: "Steps to reproduce: 1. ... 2. ...  Expected: ...  Actual: ..."
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: How you ran it. Include as much as helps us reproduce.
+      placeholder: |
+        - Boot mode: BIOS / UEFI / Secure Boot
+        - VM or hardware: e.g. QEMU 8, VirtualBox 7, Intel NUC
+        - GPU: e.g. Intel UHD, AMD Renoir, NVIDIA
+        - Language/layout: fa / en, keyboard toggle, ZWNJ
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / screenshots
+      description: Output of `journalctl -b`, `dmesg`, screenshots, or installer logs. Paste between the triple backticks.
+      render: shell
diff --git a/ISSUE_TEMPLATE/config.yml b/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🌐 Website
+    url: https://zurvanlinux.org
+    about: Zurvan Linux landing page (Persian / English).
+  - name: 📖 Specification & architecture docs
+    url: https://github.com/ZurvanLinux/ZurvanLinux
+    about: The authoritative spec set (technical-spec, package-manifest, ui-ux, distribution, qa-checklist).
+  - name: 🔒 Report a security vulnerability
+    url: https://github.com/ZurvanLinux/.github/blob/main/SECURITY.md
+    about: Do not open public issues for security problems — follow the disclosure process.
diff --git a/ISSUE_TEMPLATE/feature_request.yml b/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,45 @@
+name: ✨ Feature request
+description: Suggest an idea, package, or improvement.
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Tell us what you'd like to see. \
+        این فرم را می‌توانید به فارسی یا انگلیسی تکمیل کنید.
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What is currently hard or impossible to do?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Your proposed solution
+      description: What you'd like to happen, and any alternatives you've considered.
+    validations:
+      required: true
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component / repo
+      options:
+        - iso-builder
+        - apt-repository
+        - website
+        - branding-assets
+        - zurvan-dns-bypass
+        - welcome-app
+        - ZurvanLinux (spec docs)
+        - other
+    validations:
+      required: true
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: This aligns with the Zurvan Linux spec (see ZurvanLinux/ZurvanLinux) and isn't a Phase 2+ deferred fork.
+          required: false
diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,21 @@
+<!-- Thanks for contributing to Zurvan Linux! می‌توانید این چک‌لیست را به فارسی یا انگلیسی پر کنید. -->
+
+## Summary
+
+<!-- What does this change do, and why? Reference the spec doc section if applicable. -->
+
+## Related issue
+
+<!-- Closes #123, or "spec: package-manifest.md §5" -->
+
+## Checklist
+
+- [ ] The change follows the relevant spec doc (`technical-spec-architecture.md` / `package-manifest.md` / `ui-ux-localization-plan.md` / `distribution-update-strategy.md` / `testing-qa-checklist.md`), or I have flagged a divergence for discussion.
+- [ ] Hard constraints respected (Debian 13 amd64-only in Phase 1; Plasma 6.7 Wayland-default; non-free repos on; Vazirmatn fontconfig; ISIRI 9147 + ZWNJ on `Shift+Space`; Asia/Tehran + Jalali).
+- [ ] Persian copy (where user-visible) is correct and uses ZWNJ where needed; RTL layout verified.
+- [ ] Workflows pass (`build-iso.yml`, `publish-repo.yml`, `deploy-site.yml`, or `lint` as relevant).
+- [ ] No secrets, private keys, or personal data committed.
+
+## Notes for reviewers
+
+<!-- Anything non-obvious, follow-ups, or P0 dependencies touched. -->