[codex] contributor-friendly foundation

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -100,14 +100,11 @@ body:
       description: Paste the most relevant output only. Redact secrets.
       render: shell
 
-  - type: upload
+  - type: textarea
     id: attachments
     attributes:
       label: Screenshots, recordings, or supporting files
-      description: Upload screenshots, short recordings, repro archives, or log files. Redact secrets before uploading.
-    validations:
-      required: false
-      accept: ".png,.jpg,.jpeg,.gif,.webp,.svg,.mp4,.mov,.webm,.log,.txt,.json,.zip"
+      description: Drag in screenshots, short recordings, repro archives, or log files. Redact secrets before uploading.
 
   - type: textarea
     id: workaround

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask a support question
+    url: https://github.com/redxzeta/forkara/discussions/categories/q-a
+    about: Get setup and usage help from the Forkara community.
+  - name: Report a security vulnerability
+    url: https://github.com/redxzeta/forkara/security/advisories/new
+    about: Share suspected vulnerabilities privately with the maintainer.

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,52 @@
+name: Documentation improvement
+description: Report missing, unclear, incorrect, or outdated documentation.
+title: "[Docs]: "
+labels:
+  - documentation
+  - needs-triage
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping make Forkara easier to understand. Keep the report focused on one documentation gap.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I searched existing issues and did not find a duplicate.
+          required: true
+        - label: This is a documentation gap, not a support request or private security report.
+          required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: Documentation location
+      description: Link the page or name the file, screen, command output, or help text.
+      placeholder: docs/development.md or Settings → Providers
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is unclear or incorrect?
+      description: Explain what a reader cannot learn or what information is out of date.
+    validations:
+      required: true
+
+  - type: textarea
+    id: improvement
+    attributes:
+      label: Suggested improvement
+      description: Describe the correction, example, or structure that would help.
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add related links or screenshots. Redact secrets and private data.

.github/pull_request_template.md

@@ -1,38 +1,19 @@
-<!--
-⚠️ READ BEFORE OPENING ⚠️
+## Linked issue or agreed scope
 
-We are not actively accepting contributions right now.
+<!-- Link the accepted issue. For an eligible small bug, test, or docs change, explain the scope. -->
 
-You can still open a PR, but please do so knowing there is a high chance
-we may close it without merging it, or never review it.
+## Change summary
 
-- Small, focused PRs are strongly preferred. Bug fixes are most likely to be merged.
-- New features will most likely just annoy us.
-- 1,000+ line PRs with a bunch of new features will probably get you banned from the repo.
--->
+<!-- What changed, and why is this the smallest useful implementation? -->
 
-## What Changed
-
-<!-- Describe the change clearly and keep scope tight. -->
-
-## Why
-
-<!-- Explain the problem being solved and why this approach is the right one. -->
-
-## UI Changes
+## Verification
 
-<!-- If this PR changes UI, include clear before/after screenshots.
-     If the change involves motion or interaction, include a short video.
-     Delete this section if not applicable. -->
+<!-- List exact automated commands and manual checks, including results. -->
 
-## Verification
+## Compatibility risks
 
-<!-- List the checks you ran. For focused web tests from the repository root:
-     bun run test:web:focused src/path/to/example.test.ts -->
+<!-- Note session, reconnect, persisted-data, migration, provider, or platform risks. Write "None" if not applicable. -->
 
-## Checklist
+## UI evidence
 
-- [ ] This PR is small and focused
-- [ ] I explained what changed and why
-- [ ] I included before/after screenshots for any UI changes
-- [ ] I included a video for animation/interaction changes
+<!-- Add before/after images for visual changes and a short recording for motion or interaction changes. Write "Not applicable" otherwise. -->

.github/workflows/issue-labels.yml

@@ -1,9 +1,9 @@
-name: Issue Labels
+name: Repository Labels
 
 on:
   push:
     branches:
-      - main
+      - built-from-scratch
     paths:
       - .github/ISSUE_TEMPLATE/**
       - .github/workflows/issue-labels.yml
@@ -14,11 +14,11 @@ permissions:
 
 jobs:
   sync:
-    name: Sync issue labels
+    name: Sync repository labels
     runs-on: ubuntu-24.04
     steps:
-      - name: Ensure managed issue labels exist
-        uses: actions/github-script@v7
+      - name: Ensure managed labels exist
+        uses: actions/github-script@v8
         with:
           script: |
             const managedLabels = [
@@ -32,10 +32,55 @@ jobs:
                 color: "a2eeef",
                 description: "Requested improvement or new capability.",
               },
+              {
+                name: "documentation",
+                color: "0075ca",
+                description: "Documentation is missing, unclear, or incorrect.",
+              },
               {
                 name: "needs-triage",
                 color: "fbca04",
-                description: "Issue needs maintainer review and initial categorization.",
+                description: "Needs maintainer review and initial categorization.",
+              },
+              {
+                name: "good first issue",
+                color: "7057ff",
+                description: "Scoped, newcomer-friendly work with concrete acceptance criteria.",
+              },
+              {
+                name: "help wanted",
+                color: "008672",
+                description: "Contributor-ready work with acceptance criteria and review capacity.",
+              },
+              {
+                name: "size:XS",
+                color: "0e8a16",
+                description: "0-9 effective changed lines (test files excluded in mixed PRs).",
+              },
+              {
+                name: "size:S",
+                color: "5ebd3e",
+                description: "10-29 effective changed lines (test files excluded in mixed PRs).",
+              },
+              {
+                name: "size:M",
+                color: "fbca04",
+                description: "30-99 effective changed lines (test files excluded in mixed PRs).",
+              },
+              {
+                name: "size:L",
+                color: "fe7d37",
+                description: "100-499 effective changed lines (test files excluded in mixed PRs).",
+              },
+              {
+                name: "size:XL",
+                color: "d93f0b",
+                description: "500-999 effective changed lines (test files excluded in mixed PRs).",
+              },
+              {
+                name: "size:XXL",
+                color: "b60205",
+                description: "1,000+ effective changed lines (test files excluded in mixed PRs).",
               },
             ];
 

.github/workflows/pr-size.yml

@@ -2,119 +2,16 @@ name: PR Size
 
 on:
   pull_request_target:
+    branches:
+      - built-from-scratch
     types: [opened, reopened, synchronize, ready_for_review, converted_to_draft]
 
 permissions:
   contents: read
 
 jobs:
-  prepare-config:
-    name: Prepare PR size config
-    runs-on: ubuntu-24.04
-    outputs:
-      labels_json: ${{ steps.config.outputs.labels_json }}
-    steps:
-      - id: config
-        name: Build PR size label config
-        uses: actions/github-script@v8
-        with:
-          result-encoding: string
-          script: |
-            const managedLabels = [
-              {
-                name: "size:XS",
-                color: "0e8a16",
-                description: "0-9 effective changed lines (test files excluded in mixed PRs).",
-              },
-              {
-                name: "size:S",
-                color: "5ebd3e",
-                description: "10-29 effective changed lines (test files excluded in mixed PRs).",
-              },
-              {
-                name: "size:M",
-                color: "fbca04",
-                description: "30-99 effective changed lines (test files excluded in mixed PRs).",
-              },
-              {
-                name: "size:L",
-                color: "fe7d37",
-                description: "100-499 effective changed lines (test files excluded in mixed PRs).",
-              },
-              {
-                name: "size:XL",
-                color: "d93f0b",
-                description: "500-999 effective changed lines (test files excluded in mixed PRs).",
-              },
-              {
-                name: "size:XXL",
-                color: "b60205",
-                description: "1,000+ effective changed lines (test files excluded in mixed PRs).",
-              },
-            ];
-
-            core.setOutput("labels_json", JSON.stringify(managedLabels));
-  sync-label-definitions:
-    name: Sync PR size label definitions
-    needs: prepare-config
-    if: github.event_name != 'pull_request_target'
-    runs-on: ubuntu-24.04
-    permissions:
-      contents: read
-      issues: write
-    steps:
-      - name: Ensure PR size labels exist
-        uses: actions/github-script@v8
-        env:
-          PR_SIZE_LABELS_JSON: ${{ needs.prepare-config.outputs.labels_json }}
-        with:
-          script: |
-            const managedLabels = JSON.parse(process.env.PR_SIZE_LABELS_JSON ?? "[]");
-
-            for (const label of managedLabels) {
-              try {
-                const { data: existing } = await github.rest.issues.getLabel({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  name: label.name,
-                });
-
-                if (
-                  existing.color !== label.color ||
-                  (existing.description ?? "") !== label.description
-                ) {
-                  await github.rest.issues.updateLabel({
-                    owner: context.repo.owner,
-                    repo: context.repo.repo,
-                    name: label.name,
-                    color: label.color,
-                    description: label.description,
-                  });
-                }
-              } catch (error) {
-                if (error.status !== 404) {
-                  throw error;
-                }
-
-                try {
-                  await github.rest.issues.createLabel({
-                    owner: context.repo.owner,
-                    repo: context.repo.repo,
-                    name: label.name,
-                    color: label.color,
-                    description: label.description,
-                  });
-                } catch (createError) {
-                  if (createError.status !== 422) {
-                    throw createError;
-                  }
-                }
-              }
-            }
   label:
     name: Label PR size
-    needs: prepare-config
-    if: github.event_name == 'pull_request_target'
     runs-on: ubuntu-24.04
     permissions:
       contents: read
@@ -126,13 +23,17 @@ jobs:
     steps:
       - name: Sync PR size label
         uses: actions/github-script@v8
-        env:
-          PR_SIZE_LABELS_JSON: ${{ needs.prepare-config.outputs.labels_json }}
         with:
           script: |
             const issueNumber = context.payload.pull_request.number;
-            const managedLabels = JSON.parse(process.env.PR_SIZE_LABELS_JSON ?? "[]");
-            const managedLabelNames = new Set(managedLabels.map((label) => label.name));
+            const managedLabelNames = new Set([
+              "size:XS",
+              "size:S",
+              "size:M",
+              "size:L",
+              "size:XL",
+              "size:XXL",
+            ]);
             // Keep this aligned with the repo's test entrypoints and test-only support files.
             const testFilePatterns = [
               /(^|\/)__tests__(\/|$)/,