Improve open-source adoption and maintenance paths

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,85 @@
+name: Bug report
+description: Report a reproducible problem in the admin template.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Include the smallest reproduction you can and the verification command output you already ran.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What went wrong?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Reproduction steps
+      description: List the smallest steps needed to reproduce the issue.
+      placeholder: |
+        1. Run npm ci
+        2. Run npm run dev
+        3. Open ...
+    validations:
+      required: true
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Affected area
+      options:
+        - Template initialization
+        - App shell and layout
+        - Auth and permissions
+        - API adapter and services
+        - CRUD pages and forms
+        - Documentation
+        - Tooling or build
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version or commit
+      placeholder: v0.1.0 or commit SHA
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: OS, Node version, browser, API mode
+    validations:
+      required: true
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification
+      description: Paste relevant command output, such as npm run verify or a focused smoke script.
+      placeholder: |
+        npm run verify
+        npm run smoke:template
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I searched for existing issues covering the same problem.
+          required: true
+        - label: I can still reproduce this issue on the current default branch.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security policy
+    url: https://github.com/WeOpen/WeBase/blob/main/SECURITY.md
+    about: Report security issues privately instead of opening a public issue.
+  - name: Template extension docs
+    url: https://github.com/WeOpen/WeBase/blob/main/docs/add-admin-module.md
+    about: Review the module extension guide before opening implementation questions.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,67 @@
+name: Feature request
+description: Suggest an improvement for the template.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Prefer changes that keep the template reusable, dependency-light, and easy to verify.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user or maintainer problem would this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: Describe the desired behavior or API.
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Proposed scope
+      description: Call out the files, modules, or workflows you expect to change.
+      placeholder: README, docs, route registry, API adapter, init script, etc.
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Community and documentation
+        - Template initialization
+        - App shell
+        - API adapter
+        - Auth and permissions
+        - CRUD patterns
+        - Documentation
+        - Testing and CI
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification plan
+      description: What command output, smoke checks, or user flow should prove this is done?
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I searched for existing requests covering this idea.
+          required: true
+        - label: This proposal preserves the template's generic, reusable positioning.
+          required: true

.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      next-stack:
+        patterns:
+          - "next"
+          - "eslint-config-next"
+          - "@next/*"
+      react-stack:
+        patterns:
+          - "react"
+          - "react-dom"
+          - "@types/react"
+          - "@types/react-dom"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+- Describe the user-facing or maintainer-facing change.
+- Link the issue, docs item, or polish checklist item when applicable.
+
+## Verification
+
+- [ ] `npm run verify`
+- [ ] Focused command or smoke script for the changed area:
+
+```bash
+# paste the exact command(s) you ran
+```
+
+## Checklist
+
+- [ ] I updated docs when the template workflow or extension surface changed.
+- [ ] I avoided new dependencies or explained why they were necessary.
+- [ ] I called out any remaining risk, follow-up, or intentionally deferred work.

README.md

@@ -12,6 +12,32 @@ npm run dev
 
 Open `http://localhost:3000`, then sign in with the mock credentials below.
 
+## Template initialization
+
+The repository ships with WeBase branding in repository metadata and app metadata. To preview a conservative first-pass rename, run:
+
+```bash
+npm run init:template -- --name "Acme Admin" --short-name "Acme" --description "A production-ready Next.js admin template for Acme operations." --github-owner acme --github-repo admin-console
+```
+
+Add `--write` to apply the changes after reviewing the preview output.
+
+The script is intentionally conservative:
+
+- It updates only `package.json`, `README.md`, `public/manifest.json`, and `src/app/layout.tsx`.
+- It skips fields that no longer match the shipped WeBase defaults instead of overwriting customized values.
+- If you change `package.json` name, refresh the lockfile metadata with `npm install --package-lock-only`.
+
+## Demo
+
+Run the template locally with `npm run dev`, or use the GitHub Pages build after it has deployed from `main`: `https://weopen.github.io/WeBase/`.
+
+The demo runs in mock mode by default, so it is safe to explore CRUD flows, permissions, navigation, audit logs, settings, and `/system/health` without a backend. For demo routes, screenshot guidance, and deployment notes, see [Demo guide](docs/demo.md).
+
+## Screenshots
+
+Screenshots are intentionally not checked in until they are captured from a verified build. Recommended captures for a release are the login page, dashboard, user management, role permissions, and system health views. Store approved images under `public/screenshots/` and reference them here after verifying the files render in GitHub and the Pages site.
+
 ## Tech stack
 
 - Next.js 16 App Router
@@ -66,6 +92,7 @@ Copy `.env.example` to `.env.local` and adjust as needed:
 npm run dev
 npm run verify
 npm run lint
+npm run smoke:e2e
 npm run smoke:template
 npm run smoke:production
 npm run build
@@ -75,11 +102,18 @@ npm run start
 - `npm run dev` starts the local development server.
 - `npm run verify` runs the full CI gate: standards lint, production smoke suite, TypeScript, and production build.
 - `npm run lint` runs ESLint across the project.
+- `npm run smoke:e2e` verifies that the documented browser/E2E and backend integration workflows remain linked and reviewable without adding a browser test dependency.
 - `npm run smoke:template` verifies template extension contracts such as route registry, RBAC, API adapter, form validation, docs, status pages, theme tokens, and dashboard chart loading.
 - `npm run smoke:production` runs the production readiness smoke suite, including i18n, auth, API, permissions, CRUD, audit, accessibility, template, and `/system/health` checks.
 - `npm run build` creates a production Next.js build and verifies buildable routes.
 - `npm run start` serves the production build after `npm run build`.
 
+## CI and automation
+
+GitHub Actions runs `CI` for every pull request and for every push to `main`. The Pages deployment workflow runs only after pushes to `main`.
+
+To verify workflow status in GitHub, open the pull request or commit and inspect the status checks section. Use the Actions tab when you need job logs for `CI` or `Deploy to GitHub Pages`.
+
 ## Release verification
 
 Before connecting a real backend or deploying a release, run:
@@ -90,6 +124,8 @@ npm run verify
 
 Then open `/system/health` to confirm API mode, backend/mock status, frontend version, build target, and operational indicators.
 
+Treat the template as release-ready only after `npm run verify` passes on the release candidate and the GitHub `CI` workflow is green for the target commit. For the full release checklist, changelog alignment, and tag guidance, see [Release checklist](docs/release.md).
+
 ## Production security boundary
 
 Frontend RBAC, route guards, mock sessions, and permission-aware UI controls are template conveniences. A production backend must enforce authentication, authorization, data-scope checks, session expiry, audit logging, CSRF protection where applicable, and rate limiting. Do not treat hidden buttons or client route redirects as security controls.
@@ -102,11 +138,15 @@ PostCSS is pinned through npm `overrides` so transitive consumers use a patched
 
 - [Add an admin module](docs/add-admin-module.md)
 - [API adapter guide](docs/api-adapter.md)
+- [Backend integration contract](docs/backend-integration.md)
+- [Accessibility maturity](docs/accessibility.md)
+- [Demo guide](docs/demo.md)
 - [Permissions and RBAC](docs/permissions.md)
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)
 - [Code of conduct](CODE_OF_CONDUCT.md)
 - [Changelog](CHANGELOG.md)
+- [Release checklist](docs/release.md)
 - [Admin template hardening plan](docs/plans/2026-06-05-admin-template-hardening.md)
 
 ## API adapter note

docs/accessibility.md

@@ -0,0 +1,106 @@
+# Accessibility Maturity
+
+WeBase currently uses source-level accessibility smoke checks plus manual browser verification. This keeps open-source maintenance lightweight while documenting the minimum quality bar for contributors and downstream adopters.
+
+## Current status
+
+- Automated coverage today is source-contract smoke, not a full browser accessibility runner.
+- `npm run smoke:a11y` checks for accessible dialog, sheet, select, table, search, and icon-button patterns in source.
+- The project does not currently ship Playwright or axe-based browser automation.
+- Manual checks are still required before release or after meaningful UI changes.
+
+## Why there is no browser harness yet
+
+This repository already standardizes on small no-dependency smoke scripts under `scripts/` for template maturity checks. Adding Playwright only for open-source polish would introduce a new dependency stack, browser install flow, and maintenance surface without enough existing E2E infrastructure to justify it in this slice.
+
+The recommended near-term path is:
+
+1. Keep source smoke checks fast and explicit.
+2. Run focused manual keyboard/screen-reader checks on changed surfaces.
+3. Add browser automation later when the project needs real interaction coverage beyond static contract checks.
+
+## Automated source smoke coverage
+
+Run:
+
+```bash
+npm run smoke:a11y
+```
+
+The current script validates these patterns:
+
+- dialogs and sheets expose `role="dialog"`, `aria-modal`, labels, focus management, and `Escape` handling
+- select controls expose combobox/listbox semantics and keyboard navigation
+- tables expose header scope, selection labels, and empty-state support
+- global search exposes an accessible input and initial focus
+- icon-only buttons expose `aria-label`
+- contributor docs keep accessibility requirements visible
+
+This smoke suite is intentionally shallow. It proves that key source patterns still exist; it does not prove that the composed UI is fully accessible in a browser.
+
+## Manual browser checks
+
+Run the app locally:
+
+```bash
+npm run dev
+```
+
+Check these routes after UI or layout changes:
+
+- `/login`
+- `/dashboard`
+- `/system/users`
+- `/system/roles`
+- `/system/menus`
+- `/system/audit-logs`
+- `/system/settings`
+- `/system/components`
+
+For each changed route, verify:
+
+1. `Tab` and `Shift+Tab` move in a predictable order.
+2. Focus is visible on links, buttons, inputs, and menu triggers.
+3. `Enter` and `Space` activate buttons and selections where expected.
+4. `Escape` closes dialogs, sheets, and search overlays and returns focus to the previous trigger.
+5. Dialogs trap focus while open.
+6. Table actions, filters, and pagination are reachable without a mouse.
+7. Icon-only controls announce meaningful names.
+8. Page headings and section labels are unique and understandable out of visual context.
+9. Light/dark theme states preserve readable contrast for body text, labels, and status badges.
+10. Forbidden, error, session-expired, and network-error routes remain understandable with keyboard-only navigation.
+
+## Screen reader spot checks
+
+At minimum, do a spot check with one screen reader before release:
+
+- Windows: Narrator or NVDA
+- macOS: VoiceOver
+
+Suggested spot-check flow:
+
+1. Open `/login` and confirm form labels, password field, submit action, and validation copy are announced.
+2. Open `/system/users` and confirm the page heading, table headers, row selection, and action buttons are announced.
+3. Open a dialog or sheet and confirm title, description, and close behavior are announced correctly.
+4. Trigger a forbidden or session-expired state and confirm the status message is understandable without visual styling.
+
+## E2E placeholder workflow
+
+Run:
+
+```bash
+npm run smoke:e2e
+```
+
+This command is a no-dependency contract check that confirms the accessibility document, backend integration document, and README links stay present. It is not a browser test runner. Its purpose is to keep the documented manual E2E workflow from drifting or disappearing during template cleanup.
+
+## When to upgrade to Playwright
+
+Introduce Playwright or another browser runner when at least one of these becomes true:
+
+- auth/session flows need interaction-level regression coverage
+- contributors start breaking focus management or overlay behavior repeatedly
+- HTTP mode becomes a standard supported workflow instead of a documented integration path
+- visual/a11y regressions are hard to catch with source smoke plus manual review
+
+Until then, the current maturity target is: fast source smoke, explicit manual checks, and documented browser verification expectations.