Add feedback templates and cookbook

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://jonq.readthedocs.io
+    about: Read the full jonq documentation.

.github/ISSUE_TEMPLATE/jq-command.yml

@@ -0,0 +1,41 @@
+name: jq command I wish was easier
+description: Share a jq command or JSON task that feels too hard to remember.
+title: "Make this JSON query easier: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for real commands or tasks where jq works, but the syntax feels hard to write, remember, or explain.
+  - type: textarea
+    id: task
+    attributes:
+      label: What are you trying to do?
+      description: Describe the JSON workflow in plain language.
+      placeholder: "Example: From a GitHub API response, print repo name, stars, and pushed date as a table."
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: Small sample input
+      description: Paste the smallest JSON sample that shows the shape. Redact secrets.
+      render: json
+  - type: textarea
+    id: current-command
+    attributes:
+      label: Current jq command, shell pipeline, or workaround
+      description: Paste the command you use today, if you have one.
+      render: bash
+  - type: textarea
+    id: ideal
+    attributes:
+      label: What would a readable jonq command look like?
+      description: Optional. Rough syntax is fine.
+      render: bash
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: This is about exploring or reshaping JSON from the terminal.
+        - label: This does not require joins, window functions, or a long-running database.

.github/ISSUE_TEMPLATE/json-edge-case.yml

@@ -0,0 +1,58 @@
+name: JSON file jonq struggled with
+description: Report a JSON shape, key name, input mode, or query that broke or behaved badly.
+title: "JSON edge case: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this when jonq gives a confusing error, wrong suggestion, surprising output, or cannot inspect/query a JSON shape cleanly.
+  - type: textarea
+    id: command
+    attributes:
+      label: Command
+      description: Paste the exact jonq command you ran.
+      render: bash
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: Small sample input
+      description: Paste the smallest JSON or NDJSON sample that reproduces it. Redact secrets.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected result
+      description: What did you expect jonq to print or suggest?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual result
+      description: Paste the output, traceback, or confusing suggestion.
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output from `jonq --version`.
+      placeholder: "jonq 0.3.4"
+  - type: dropdown
+    id: input-mode
+    attributes:
+      label: Input mode
+      options:
+        - file
+        - stdin
+        - URL
+        - glob
+        - NDJSON
+        - follow mode
+        - streaming mode
+        - Python API

.github/ISSUE_TEMPLATE/workflow-request.yml

@@ -0,0 +1,40 @@
+name: Workflow request
+description: Suggest a real terminal JSON workflow that jonq should make smoother.
+title: "Workflow: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for workflows, not isolated syntax wishes. The best requests include a source of JSON, the desired output, and what you do after that output.
+  - type: textarea
+    id: workflow
+    attributes:
+      label: Workflow
+      description: What are you doing from start to finish?
+      placeholder: "Example: curl an API, inspect unknown fields, extract a few nested values, and save CSV for a spreadsheet."
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: Example input or source
+      description: Link to an API/docs page or paste a small sample. Redact secrets.
+      render: json
+  - type: textarea
+    id: output
+    attributes:
+      label: Desired output
+      description: Show the table, CSV, JSONL, raw values, or JSON shape you want.
+      render: text
+  - type: textarea
+    id: current-tools
+    attributes:
+      label: What tools do you use today?
+      description: jq, gron, jello, Python, DuckDB, shell scripts, spreadsheet import, etc.
+  - type: checkboxes
+    id: direction
+    attributes:
+      label: Direction check
+      options:
+        - label: This would help with common JSON exploration or extraction.
+        - label: This should stay readable and not turn jonq into a full database or ETL system.

README.md

@@ -447,6 +447,7 @@ jonq --completions fish > ~/.config/fish/completions/jonq.fish
 ## Documentation
 
 - Full docs: https://jonq.readthedocs.io/en/latest/
+- Cookbook: https://jonq.readthedocs.io/en/latest/cookbook.html
 - Syntax reference: [SYNTAX.md](SYNTAX.md)
 - Usage examples: [USAGE.md](USAGE.md)
 - Contributing: [CONTRIBUTIONS.md](CONTRIBUTIONS.md)

docs/source/cookbook.rst

@@ -0,0 +1,144 @@
+Cookbook
+========
+
+These recipes focus on the workflows jonq is meant to make fast: inspect unknown JSON, find the fields you need, and turn the result into a useful terminal-friendly shape.
+
+jonq is still a jq-powered exploration and extraction tool. If the task becomes joins, window functions, repeated analytical queries, or long-running pipelines with connectors, use a database or ETL system instead.
+
+Inspect Unknown JSON First
+--------------------------
+
+When you do not know the shape yet, run jonq without a query:
+
+.. code-block:: bash
+
+   jonq data.json
+
+Smart Inspect prints the root shape, discovered fields, sample values, a sample object, and suggested queries. This is usually the first step before writing a filter.
+
+Typical workflow:
+
+1. Inspect the payload.
+2. Copy one of the suggested queries.
+3. Narrow fields and filters.
+4. Switch output format once the query is correct.
+
+.. code-block:: bash
+
+   jonq data.json "select id, name, status" -t
+   jonq data.json "select id, name, status if status = 'active'" -t
+   jonq data.json "select id, name, status if status = 'active'" --format csv > active.csv
+
+Turn API JSON Into a Table
+--------------------------
+
+Many APIs return arrays of objects. jonq is useful when you want a few readable columns instead of a large JSON blob.
+
+.. code-block:: bash
+
+   curl -s https://api.github.com/users/octocat/repos \
+     | jonq "select name, stargazers_count as stars, pushed_at sort stargazers_count desc limit 10" -t
+
+When you need the generated jq filter, add ``--explain``:
+
+.. code-block:: bash
+
+   curl -s https://api.github.com/users/octocat/repos \
+     | jonq "select name, stargazers_count as stars limit 5" --explain
+
+Flatten Nested Arrays
+---------------------
+
+Use ``from`` when the rows you care about live inside nested arrays.
+
+.. code-block:: json
+
+   [
+     {
+       "name": "Alice",
+       "orders": [
+         {"order_id": 101, "item": "Laptop", "price": 1200},
+         {"order_id": 102, "item": "Phone", "price": 800}
+       ]
+     },
+     {
+       "name": "Bob",
+       "orders": [
+         {"order_id": 103, "item": "Tablet", "price": 500}
+       ]
+     }
+   ]
+
+.. code-block:: bash
+
+   jonq users.json "select order_id, item, price from [].orders if price > 700" -t
+
+This treats each order as a row and then filters by ``price``.
+
+Export JSON to CSV or JSONL
+---------------------------
+
+Use CSV when the next step is a spreadsheet or a tabular tool:
+
+.. code-block:: bash
+
+   jonq users.json "select id, name, city" --format csv > users.csv
+
+Use JSONL when the next step expects one JSON object per line:
+
+.. code-block:: bash
+
+   jonq users.json "select id, name, city" --format jsonl > users.jsonl
+
+Use raw output for shell loops and simple command substitution:
+
+.. code-block:: bash
+
+   jonq users.json "select name" -r
+
+Follow NDJSON Logs
+------------------
+
+For newline-delimited JSON logs, combine ``tail -f`` with ``--follow``:
+
+.. code-block:: bash
+
+   tail -f app.ndjson \
+     | jonq --follow "select timestamp, level, message if level = 'error'" -t
+
+This is for line-by-line log inspection. Use non-follow mode when you need global operations such as grouping, sorting, distinct, or aggregation.
+
+Recover From Field Typos
+------------------------
+
+If you mistype a field, jonq validates the query against the payload and prints a copy-pasteable repair suggestion:
+
+.. code-block:: bash
+
+   jonq users.json "select nme"
+
+.. code-block:: text
+
+   Error: Unknown field(s): nme
+   Did you mean: nme -> name?
+   Available fields: id, name, age, city
+   Try: jonq users.json "select name"
+
+This is most useful while exploring unfamiliar payloads where field names are long, nested, or easy to mistype.
+
+Know When to Drop to jq
+-----------------------
+
+Use raw jq when you need full jq language control, complex reductions, custom recursive transforms, or jq modules.
+
+Use jonq when the task is common enough to read like:
+
+.. code-block:: text
+
+   select these fields
+   from this nested array
+   where this condition is true
+   sort and limit the rows
+   print as table, CSV, JSONL, YAML, JSON, or raw values
+
+That boundary keeps jonq useful without turning it into a second full query language.

docs/source/index.rst

@@ -51,6 +51,7 @@ Key Features
    installation
    usage
    usage_in_python
+   cookbook
    comparison
    examples
    api