📝 README updates

Removes Future section (moved to GitHub issues). Adds TOC and
reorganizes.

[skip-ci]

README.md

@@ -2,15 +2,25 @@
 
 Basic TypeScript declaration generator for CSS files.
 
-## Install
+**Table of contents**
+
+- [Usage](#usage)
+- [Recipes](#recipes)
+- [Motivation](#motivation)
+- [Contributing](#contributing)
+- [Implementation details](#implementation-details)
+
+## Usage
+
+### Install
 
 Install the CLI tool as a dev dependency.
 
 ```shell
 npm install --save-dev css-typed
 ```
 
-## Usage
+### Run
 
 Run `css-typed` and pass it a glob targeting your CSS files.
 
@@ -24,7 +34,7 @@ This will generate `.d.css.ts` files next to the original source files.
 >
 > A CSS module file with the name `foo.module.css` will emit `foo.module.d.css.ts`.
 
-## Configuration
+### Configure
 
 Configure TypeScript to allow arbitrary extensions (TS 5+).
 
@@ -74,16 +84,6 @@ Feel free to [nodemon] or similar.
 
 [nodemon]: https://www.npmjs.com/package/nodemon
 
-## Details
-
-This (very basic) implementation uses [glob] for file matching and [css-tree] for CSS parsing.
-It extracts CSS classes (`ClassSelector` in CSS Tree’s AST) and exports them as `string` constants (named exports).
-
-I chose CSS Tree after a brief search because it had a nice API, good documentation, and supported CSS nesting (a requirement for my original use case).
-
-[glob]: https://www.npmjs.com/package/glob
-[css-tree]: https://www.npmjs.com/package/css-tree
-
 ## Motivation
 
 [typescript-plugin-css-modules] provides a great IDE experience, but cannot perform build-failing type-checking.
@@ -97,7 +97,8 @@ declare module "*.module.css" {
 }
 ```
 
-[typed-css-modules] and [typed-scss-modules] exist, but the former does not have recent activity and the latter focuses on SCSS (and my current (2023) interests involve modern CSS only).
+[typed-css-modules] and [typed-scss-modules] exist, but the former does not have recent activity and the latter focuses on SCSS.
+(My current (2023/2024) interests involve modern CSS only.)
 Both depend on [css-modules-loader-core], which appears [abandoned][174].
 
 Therefore, I wrote my own (very basic) implementation.
@@ -112,15 +113,12 @@ Therefore, I wrote my own (very basic) implementation.
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-## Future
+## Implementation details
+
+This (very basic) implementation uses [glob] for file matching and [css-tree] for CSS parsing.
+It extracts CSS classes (`ClassSelector` in CSS Tree’s AST) and exports them as `string` constants (named exports).
 
-This (very basic) implementation suited my immediate needs, but I see some improvements we could make.
-_All naming subject to bike shedding._
+I chose CSS Tree after a brief search because it had a nice API, good documentation, and supported CSS nesting (a requirement for my original use case).
 
-- `ext`: Traditional (pre TS 5) extension naming with `*.css.d.ts`
-- `ignore`: Ignore support
-- `format`: Class name formatting
-  - (Related) Gracefully handle invalid names (example: kebab case)
-- `outDir`: Publish to a directory instead of next to the sources
-- `watch`: First-class watch mode
-- General CLI/UX improvements
+[glob]: https://www.npmjs.com/package/glob
+[css-tree]: https://www.npmjs.com/package/css-tree