docs: polish first release documentation

.github/ISSUE_TEMPLATE/100-bug-report.yml

@@ -8,7 +8,7 @@ body:
     attributes:
       value: >
         Before submitting, please search
-        [existing issues](https://github.com/mlsys-io/lumilake/issues?q=is%3Aissue+sort%3Acreated-desc+)
+        [existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
         to avoid duplicates.
 
   - type: dropdown
@@ -20,9 +20,11 @@ body:
         - Server / API routes
         - Runtime / scheduler / optimizer
         - Ops / operators
+        - SDK
         - CLI (lumilake)
         - Deploy / Docker
         - Graphs / YAML / n8n parser
+        - Hooks / plugins
         - Documentation
         - Other
     validations:

.github/ISSUE_TEMPLATE/200-deployment.yml

@@ -1,65 +1,80 @@
-name: Deployment issue
-description: Something went wrong with `lumilake deploy up/down/reset` or the Docker stack.
+name: Deployment / Installation
+description: Report an issue with installing or deploying Lumilake.
 title: "[Deploy]: "
-labels: ["deploy"]
+labels: ["deployment"]
 
 body:
+  - type: markdown
+    attributes:
+      value: >
+        Before submitting, please search
+        [existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
+        to avoid duplicates.
+
   - type: dropdown
-    id: mode
+    id: deployment
     attributes:
-      label: Deploy mode
+      label: Deployment method
       options:
-        - lumid.data
-        - Direct PostgreSQL + S3
-        - Server only
+        - Local (uv / pip)
+        - Docker Compose (dev)
+        - Bundled FlowMesh stack
+        - External FlowMesh
+        - Other
     validations:
       required: true
 
-  - type: textarea
+  - type: dropdown
+    id: data_plane
     attributes:
-      label: Command and output
-      description: |
-        Paste the exact command and full output (wrap in triple-backticks).
-      placeholder: |
-        ```
-        $ uv run lumilake deploy up
-        [deploy] ...
-        ```
+      label: Data plane
+      options:
+        - lumid.data
+        - Direct PostgreSQL + S3-compatible storage
+        - Not configured yet
+        - Multiple / unclear
     validations:
       required: true
 
   - type: textarea
     attributes:
-      label: .env (redacted)
+      label: Describe the issue
       description: |
-        Your ``.env`` with secrets redacted.
+        What went wrong during installation or deployment?
+        Include the commands you ran and the full error output.
       placeholder: |
-        ```dotenv
-        LUMILAKE_SERVER_PORT="9000"
-        LUMILAKE_RUNTIME_ORCHESTRATOR_URL="http://127.0.0.1:18000"
-        LUMID_DATA_URL="http://127.0.0.1:9102"
+        Steps to reproduce:
+        1. ...
+
+        ```
+        Error output
         ```
     validations:
       required: true
 
-  - type: textarea
-    attributes:
-      label: Container status and logs
-      description: |
-        Output of ``docker ps --filter name=lumilake`` plus
-        relevant ``docker logs <container>`` excerpts.
-
   - type: textarea
     attributes:
       label: Environment
+      description: >
+        Lumilake version/commit, OS, Docker version, Docker Compose version,
+        Python version, and runtime/data-plane mode.
       value: |
         - Lumilake version:
         - OS:
         - Docker version:
         - Docker Compose version:
+        - Python version:
+        - Runtime / data plane:
     validations:
       required: true
 
+  - type: textarea
+    attributes:
+      label: Relevant config / logs
+      description: >
+        Paste relevant .env settings with secrets redacted, container status,
+        or logs. Use triple-backtick blocks.
+
   - type: checkboxes
     attributes:
       label: Before submitting

.github/ISSUE_TEMPLATE/300-feature-request.yml

@@ -1,30 +1,62 @@
 name: Feature request
-description: Suggest a new capability for Lumilake.
+description: Propose a new feature or enhancement.
 title: "[Feature]: "
-labels: ["enhancement"]
+labels: ["feature request"]
 
 body:
+  - type: markdown
+    attributes:
+      value: >
+        Before submitting, please search
+        [existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
+        to avoid duplicates.
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which component does this feature relate to?
+      options:
+        - Server / API routes
+        - Runtime / scheduler / optimizer
+        - Ops / operators
+        - SDK
+        - CLI
+        - Deploy / Docker
+        - Graphs / YAML / n8n parser
+        - Hooks / plugins
+        - Other
+    validations:
+      required: true
+
   - type: textarea
     attributes:
-      label: Problem
-      description: |
-        What are you trying to do today and why is it hard?
+      label: Motivation
+      description: >
+        What problem does this solve? Is it related to a specific workflow or
+        use case? e.g., "When running multi-stage data workflows, I need X because..."
     validations:
       required: true
 
   - type: textarea
     attributes:
       label: Proposed solution
-      description: |
-        How would you like it to work? Sketch an API / CLI shape if helpful.
+      description: >
+        A clear description of what you'd like to happen.
     validations:
       required: true
 
   - type: textarea
     attributes:
       label: Alternatives considered
-      description: |
-        Workarounds you've tried, or alternate designs you considered.
+      description: >
+        Any alternative solutions or workarounds you've considered.
+
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: >
+        Any other context, mockups, or examples.
 
   - type: checkboxes
     attributes:

.github/ISSUE_TEMPLATE/400-new-optimizer.yml

@@ -1,36 +1,63 @@
 name: New optimizer strategy
 description: Propose a new scheduling / optimization strategy.
 title: "[Optimizer]: "
-labels: ["optimizer"]
+labels: ["optimizer", "feature request"]
 
 body:
+  - type: markdown
+    attributes:
+      value: >
+        Lumilake currently ships HALO in-tree. Custom optimizers can also be
+        registered as Lumilake plugins.
+
   - type: input
     id: name
     attributes:
       label: Optimizer name
-      description: |
-        e.g. ``halo-v2``, ``cost-greedy``, ``spot-aware``.
+      description: >
+        Name of the proposed optimizer and the scheduling approach it uses
+        (e.g. "spot-aware cost optimizer").
     validations:
       required: true
 
   - type: textarea
     attributes:
       label: Motivation
-      description: |
-        What scheduling problem does this solve that the existing strategies
-        (``dummy``, ``halo``) don't handle well?
+      description: >
+        What use case does this enable? Why can't HALO or an existing plugin
+        optimizer cover it?
     validations:
       required: true
 
   - type: textarea
     attributes:
-      label: Approach
-      description: |
-        Short design sketch. How does the planner build its plan? What signals
-        from the runtime does it use? What's the complexity?
+      label: Expected input / output
+      description: >
+        Describe the runtime graph shape, worker/resource signals, data-profile
+        inputs, and expected schedule output. A sample workflow YAML snippet is helpful.
+      placeholder: |
+        ```yaml
+        nodes:
+          ...
+        ```
+
+  - type: dropdown
+    id: plugin
+    attributes:
+      label: Should this be a plugin?
+      options:
+        - "Yes"
+        - "No"
+        - Depends on design
     validations:
       required: true
 
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: >
+        Links to related papers, benchmarks, workloads, or existing implementations.
+
   - type: checkboxes
     attributes:
       label: Before submitting

.github/ISSUE_TEMPLATE/500-documentation.yml

@@ -1,32 +1,29 @@
 name: Documentation
-description: Something in the docs, README, or CONTRIBUTING is unclear, wrong, or missing.
-title: "[Docs]: "
+description: Report a documentation issue or suggest improvements.
+title: "[Doc]: "
 labels: ["documentation"]
 
 body:
-  - type: input
-    id: location
+  - type: markdown
     attributes:
-      label: Where
-      description: |
-        Path to the file, or URL of the page. e.g. ``README.md``, ``CONTRIBUTING.md``, ``CLAUDE.md``, ``docs/``.
-    validations:
-      required: true
+      value: >
+        Before submitting, please search
+        [existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
+        to avoid duplicates.
 
   - type: textarea
     attributes:
-      label: What's wrong or missing?
-      description: |
-        Quote the specific text if it's misleading, or describe what you
-        were looking for and couldn't find.
+      label: Describe the issue
+      description: >
+        What is missing, incorrect, or unclear in the documentation?
     validations:
       required: true
 
   - type: textarea
     attributes:
       label: Suggested fix
-      description: |
-        Proposed replacement text or new section outline, if you have one.
+      description: >
+        How could the documentation be improved?
 
   - type: checkboxes
     attributes:

.github/ISSUE_TEMPLATE/600-performance.yml

@@ -1,49 +1,44 @@
-name: Performance issue
-description: A submission, schedule, or execution is unexpectedly slow / expensive.
-title: "[Perf]: "
+name: Performance discussion
+description: Report a performance regression or propose an optimization.
+title: "[Performance]: "
 labels: ["performance"]
 
 body:
+  - type: markdown
+    attributes:
+      value: >
+        Before submitting, please search
+        [existing issues](https://github.com/mlsys-io/lumilake_OSS/issues?q=is%3Aissue+sort%3Acreated-desc+)
+        to avoid duplicates.
+
   - type: dropdown
-    id: surface
+    id: category
     attributes:
-      label: Where is the slowness?
+      label: Category
       options:
-        - /jobs/preview (graph compile)
-        - /jobs (submission + first schedule)
-        - Scheduler (HALO / dummy optimizer)
-        - Data profiling
-        - Output dump at finalize
-        - FlowMesh dispatch / worker assignment
-        - Other
+        - Performance regression
+        - Optimization proposal
+        - Benchmarking / profiling
     validations:
       required: true
 
   - type: textarea
     attributes:
-      label: Workload
+      label: Description
       description: |
-        A minimal YAML workflow (or CLI command) that reproduces the slowness.
+        For regressions: provide before/after measurements, the commit or version
+        where regression started, and the workflow used to benchmark.
+
+        For proposals: describe the bottleneck and your proposed optimization.
     validations:
       required: true
 
-  - type: textarea
-    attributes:
-      label: Observed timing
-      description: |
-        Paste wall-clock numbers or profile snapshots. Compare against what
-        you expected if possible.
-
   - type: textarea
     attributes:
       label: Environment
-      value: |
-        - Lumilake version:
-        - Optimizer: (dummy / halo / ...)
-        - CPU / GPU:
-        - Compute DB size (rough):
-    validations:
-      required: true
+      description: >
+        Lumilake version, hardware (CPU/GPU), runtime mode, data-plane mode,
+        worker count, and any relevant config.
 
   - type: checkboxes
     attributes: