This repository is a mega-umbrella that plays six roles at once. VISION.md is the canonical overview; the table below is the two-line tour:

Each role is documented in VISION.md. The rest of this README focuses on role #1 (community-health inheritance) and role #6 (reusable workflows) — the two roles other FlexNetOS repos interact with directly.

For maintainer responsibilities see MAINTAINERS.md; for the release cadence and the v1 moving-tag policy see RELEASING.md; for operational best-practices docs see docs/README.md.

GitHub treats a User-owned (or Organization-owned) repository named .github as a fallback: any community health file present here is automatically used by every other repo under the same account that does not define its own. See GitHub's documentation on default community health files.

The files GitHub picks up as defaults for every FlexNetOS repo (role #1), plus the reusable workflows callers consume (role #6). For the other four roles see VISION.md.

.
├── LICENSE                         MIT
├── CODE_OF_CONDUCT.md              Contributor Covenant 2.1
├── CONTRIBUTING.md                 Commit conventions, PR expectations, branch policy
├── SECURITY.md                     Private vulnerability reporting, supported versions, SLA
├── SUPPORT.md                      Where to ask for help (Issues vs Discussions vs email)
├── FUNDING.yml                     Sponsorship handles (template placeholders)
├── VISION.md                       The six-role overview
├── MAINTAINERS.md                  Ownership, contact, escalation
├── RELEASING.md                    Tagging policy, release-please loop, the `v1` moving tag
├── profile/
│   └── README.md                   Public landing page rendered at github.com/FlexNetOS
├── docs/
│   ├── README.md                   Index of operational docs
│   ├── automation.md               Scheduled workflows and how their outputs flow back
│   ├── fork-workflow.md            Fork-and-track pattern, upstream syncing, release-tag sync
│   ├── directory-layout.md         On-disk convention for forks vs upstream vs first-party
│   └── self-hosted-runner.md       Safety guidance + ephemeral-runner migration path
└── .github/
    ├── CODEOWNERS                  Reviewer routing
    ├── PULL_REQUEST_TEMPLATE.md
    ├── ISSUE_TEMPLATE/
    │   ├── config.yml              Disables blank issues, adds contact links
    │   ├── bug_report.yml          Modern YAML issue form
    │   ├── feature_request.yml
    │   └── documentation.yml
    ├── dependabot.yml              Weekly bumps for GitHub Actions used here
    └── workflows/
        ├── reusable-lint.yml       workflow_call · language-agnostic lint dispatcher
        ├── reusable-typecheck.yml  workflow_call · TypeScript type checker (tsc --noEmit)
        ├── reusable-test.yml       workflow_call · test dispatcher
        ├── reusable-build.yml      workflow_call · build dispatcher
        ├── reusable-security.yml   workflow_call · CodeQL + Trivy + Gitleaks
        ├── reusable-release.yml    workflow_call · release-please / semantic-release
        ├── reusable-secrets.yml    workflow_call · pass-based secret injection
        └── reusable-submodule-bump.yml

For any file in this repo's root or .github/ that GitHub recognises as a "community health file" (CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, SUPPORT.md, FUNDING.yml, the issue & PR templates), GitHub will display it on any other FlexNetOS repo that does not ship its own version of that file.

To override for a specific repo, simply commit a local copy. The local copy wins; the fallback in this repo is ignored for that repo only.

The profile/README.md is a separate mechanism: it renders as the public landing page at https://github.com/FlexNetOS (above the repo grid).

These are intentionally scaffolds today — they ship the workflow_call shape, documented inputs, least-privilege permissions: blocks, and a placeholder body. Bodies will be filled in by follow-on work.

In any FlexNetOS repo, drop a thin caller into .github/workflows/ci.yml:

name: ci
on: [push, pull_request]

jobs:
  lint:
    uses: FlexNetOS/.github/.github/workflows/reusable-lint.yml@main
    with:
      language: bun
    secrets: inherit

  typecheck:
    needs: lint
    uses: FlexNetOS/.github/.github/workflows/reusable-typecheck.yml@main
    with:
      language: bun
    secrets: inherit

  test:
    needs: typecheck
    uses: FlexNetOS/.github/.github/workflows/reusable-test.yml@main
    with:
      language: bun
    secrets: inherit

Once the scaffolds get real bodies and we cut tagged releases, callers should pin to a moving major tag (@v1) so non-breaking improvements propagate automatically while breaking changes force a deliberate bump.

The docs/ directory contains write-ups that resolve recurring engineering questions across FlexNetOS repos. Link to them from any repo's README:

• Fork-and-track workflow — the right way to carry local patches on a third-party repo while staying current with upstream releases.
• Directory layout for local checkouts — where forks, read-only clones, and first-party projects live on disk.
• Self-hosted runner safety — current inventory, untrusted-PR risk, label discipline, and the ephemeral-runner migration path.
• Submodule vision — ASCII diagrams for the umbrella/submodule graph, nested repo plugins, and storage model.
• Linked submodule workflows — how parent workflows can dispatch child and nested submodule automation.

git clone https://github.com/FlexNetOS/.github.git
cd .github

# Lint workflows (uses pinned repo-local actionlint wrapper)
tools/bin/actionlint .github/workflows/*.yml

# Lint markdown (no install needed)
python3 scripts/verify-markdown.py .

The main branch is protected: PR with one approval, linear history, no force-push, no deletion. See CONTRIBUTING.md for the commit-message convention and branch policy.

See MAINTAINERS.md for ownership, contact, and escalation. Private vulnerability reports go through SECURITY.md.

• Phase 6 (GitHub App automation) must not proceed until the Vaultwarden→GitHub secret sync is green on main for at least 3 consecutive runs.