chore: Enhance documentation with detailed usage examples and new sections for operations, clauses, and filters

README.md

@@ -28,75 +28,32 @@ $ gcloud auth application-default login
 
 ## Usage
 
-### Basic
-
 ```sh
 $ fscli --project-id my-project
-> QUERY users
-+----------------------+---------+-----+
-|          ID          |  name   | age |
-+----------------------+---------+-----+
-| VfsA2DjQOWQmJ1LI8Xee | shigeru |  20 |
-| ewpSGf5URC1L1vPENbxh | takashi |  20 |
-+----------------------+---------+-----+
-> QUERY users WHERE age = 20
-+----------------------+---------+-----+
-|          ID          |  name   | age |
-+----------------------+---------+-----+
-| VfsA2DjQOWQmJ1LI8Xee | shigeru |  20 |
-| ewpSGf5URC1L1vPENbxh | takashi |  20 |
-+----------------------+---------+-----+
-> QUERY users WHERE name = "takashi" AND age = 20;
-+----------------------+---------+-----+
-|          ID          |  name   | age |
-+----------------------+---------+-----+
-| ewpSGf5URC1L1vPENbxh | takashi |  20 |
-+----------------------+---------+-----+
-> GET users/ewpSGf5URC1L1vPENbxh
-+----------------------+---------+-----+
-|          ID          |  name   | age |
-+----------------------+---------+-----+
-| ewpSGf5URC1L1vPENbxh | takashi |  20 |
-+----------------------+---------+-----+
-> QUERY users SELECT name WHERE age = 20 ORDER BY name ASC LIMIT 1
-+----------------------+---------+
-|          ID          |  name   |
-+----------------------+---------+
-| VfsA2DjQOWQmJ1LI8Xee | shigeru |
-+----------------------+---------+
-> QUERY posts WHERE tags ARRAY_CONTAINS 'tech'
-+----------------------+------------+----------------+
-|          ID          |   title    |      tags      |
-+----------------------+------------+----------------+
-| nOsNxixUQ1rqNwVJz56O | First post | [tech finance] |
-+----------------------+------------+----------------+
-> COUNT users
-2
-> COUNT users WHERE name = "takashi"
-1
-> \d
-users
-posts
-groups
-> \d groups/yvPWOCcd4CvfUr2POuXk
-members
 ```
 
-### Non-Interactive Mode
+| Flag | Description |
+|------|-------------|
+| `--project-id` | Firebase project ID (required) |
+| `--out-mode` | Output format: `table` (default) or `json` |
 
-`fscli` can be used in non-interactive mode by piping commands to it. This is useful for scripting and automation.
+### Quick Examples
 
-**Example: Get a single document and extract a field**
-```sh
-$ echo "GET users/user123" | fscli --project-id my-project --out-mode json | jq '.data.name'
-"Test User"
+```sql
+QUERY users
+QUERY users WHERE age = 20
+QUERY users SELECT name WHERE age >= 20 ORDER BY name ASC LIMIT 10
+GET users/ewpSGf5URC1L1vPENbxh
+COUNT users WHERE name = "takashi"
 ```
 
-**Example: Query a collection and get the ID of the first result**
-```sh
-$ echo "QUERY users WHERE age > 25" | fscli --project-id my-project --out-mode json | jq '.[0].id'
-"user123"
-```
+## Documentation
+
+- [Operations](docs/operations.md) — `QUERY`, `GET`, `COUNT`, collection paths
+- [WHERE Filters](docs/where-filters.md) — Operators (`=`, `!=`, `>`, `<`, `IN`, `ARRAY_CONTAINS`, ...), value types, `TIMESTAMP()`, `__id__`
+- [Clauses](docs/clauses.md) — `SELECT`, `ORDER BY`, `LIMIT`
+- [Meta Commands](docs/meta-commands.md) — `\d`, `\pager`
+- [Output](docs/output.md) — Table / JSON output modes, non-interactive mode
 
 ### JSON mode
 

docs/clauses.md

@@ -0,0 +1,66 @@
+# Clauses
+
+## SELECT
+
+Specify which fields to include in the output. Works with `QUERY` and `GET` operations.
+
+```
+SELECT <field1> [, <field2>, ...]
+```
+
+The document `ID` column is always included.
+
+### Examples
+
+```sql
+QUERY users SELECT name
+QUERY users SELECT name, age, email
+GET users/abc123 SELECT name, age
+```
+
+## ORDER BY
+
+Sort results by one or more fields. Works with `QUERY` operation only.
+
+```
+ORDER BY <field1> [ASC|DESC] [, <field2> [ASC|DESC], ...]
+```
+
+- **ASC** — Ascending order (default if omitted)
+- **DESC** — Descending order
+
+### Examples
+
+```sql
+-- Ascending (default)
+QUERY users ORDER BY name
+
+-- Descending
+QUERY users ORDER BY age DESC
+
+-- Multiple fields
+QUERY users ORDER BY age ASC, name DESC
+```
+
+## LIMIT
+
+Limit the number of returned documents. Works with `QUERY` operation only.
+
+```
+LIMIT <count>
+```
+
+### Examples
+
+```sql
+QUERY users LIMIT 10
+QUERY users ORDER BY age DESC LIMIT 5
+```
+
+## Combining Clauses
+
+Clauses can be combined in a single query:
+
+```sql
+QUERY users SELECT name WHERE age >= 20 ORDER BY name ASC LIMIT 10
+```

docs/meta-commands.md

@@ -0,0 +1,44 @@
+# Meta Commands
+
+Meta commands start with `\` and provide utility functions outside of Firestore queries.
+
+## \d — List Collections
+
+List collections at the root level or subcollections of a specific document.
+
+```
+\d [document_path]
+```
+
+### Examples
+
+```
+-- List root-level collections
+> \d
+users
+posts
+groups
+
+-- List subcollections of a document
+> \d groups/yvPWOCcd4CvfUr2POuXk
+members
+```
+
+## \pager — Toggle Output Paging
+
+Enable or disable paging for large output. Uses the `$PAGER` environment variable, or falls back to `less`.
+
+```
+\pager on
+\pager off
+```
+
+### Examples
+
+```
+-- Enable pager
+> \pager on
+
+-- Disable pager
+> \pager off
+```

docs/operations.md

@@ -0,0 +1,77 @@
+# Operations
+
+fscli supports three operations: `QUERY`, `GET`, and `COUNT`.
+
+## QUERY
+
+Query documents in a collection. Supports `SELECT`, `WHERE`, `ORDER BY`, and `LIMIT` clauses.
+
+```
+QUERY <collection_path> [SELECT ...] [WHERE ...] [ORDER BY ...] [LIMIT ...]
+```
+
+### Examples
+
+```sql
+-- Query all documents
+QUERY users
+
+-- Query with filter
+QUERY users WHERE age = 20
+
+-- Subcollection query
+QUERY users/abc123/posts
+```
+
+## GET
+
+Fetch a single document by its full path.
+
+```
+GET <document_path> [SELECT ...]
+```
+
+The document path must have an odd number of segments (e.g., `collection/docId`).
+
+### Examples
+
+```sql
+-- Get a single document
+GET users/ewpSGf5URC1L1vPENbxh
+
+-- Get with field selection
+GET users/ewpSGf5URC1L1vPENbxh SELECT name, age
+```
+
+## COUNT
+
+Count documents in a collection. Supports `WHERE` clause for filtering.
+
+```
+COUNT <collection_path> [WHERE ...]
+```
+
+Returns a single integer.
+
+### Examples
+
+```sql
+-- Count all documents
+COUNT users
+
+-- Count with filter
+COUNT users WHERE name = "takashi"
+```
+
+## Collection Path
+
+Collection paths support nested subcollections using the format:
+
+```
+collection/docId/subcollection/docId/subcollection/...
+```
+
+- **Collection path** (even number of segments): `users`, `users/abc123/posts`
+- **Document path** (odd number of segments): `users/abc123`, `users/abc123/posts/xyz789`
+
+Leading slashes are automatically stripped.

docs/output.md

@@ -0,0 +1,55 @@
+# Output
+
+## Output Modes
+
+fscli supports two output formats, configurable via the `--out-mode` flag.
+
+### Table (default)
+
+ASCII table format with headers.
+
+```sh
+$ fscli --project-id my-project
+> QUERY users
++----------------------+---------+-----+
+|          ID          |  name   | age |
++----------------------+---------+-----+
+| VfsA2DjQOWQmJ1LI8Xee | shigeru |  20 |
+| ewpSGf5URC1L1vPENbxh | takashi |  20 |
++----------------------+---------+-----+
+```
+
+### JSON
+
+Structured JSON output, suitable for piping to tools like `jq`.
+
+```sh
+$ fscli --project-id my-project --out-mode json
+```
+
+**GET output:**
+
+```json
+{"id": "documentId", "data": {"name": "takashi", "age": 20}}
+```
+
+**QUERY output:**
+
+```json
+[
+  {"id": "doc1", "data": {"name": "shigeru", "age": 20}},
+  {"id": "doc2", "data": {"name": "takashi", "age": 20}}
+]
+```
+
+## Non-Interactive Mode
+
+fscli can be used in non-interactive mode by piping commands via stdin. This is useful for scripting and automation.
+
+```sh
+# Get a single document and extract a field
+echo "GET users/user123" | fscli --project-id my-project --out-mode json | jq '.data.name'
+
+# Query and get the ID of the first result
+echo "QUERY users WHERE age > 25" | fscli --project-id my-project --out-mode json | jq '.[0].id'
+```