charlie: Documentation Update

[shellscape]

Please examine the current state of the code and examine all of the markdown files in the docs directory. A quick examination was done in this comment https://github.com/shellscape/postcss-values-parser/issues/152#issuecomment-3480873690 but it is not comprehensive. Please look for an identify any and all discrepancies, including those pointed out in that Github comment. Open a PR to resolve any issues with the documentation that are found.

[charliecreates[bot]]

Expand this to see my work.

• Created feature branch ai-153-charlie-documentation-update to stage the documentation changes for #153: branch.
• Validated ParseError/AstError docs against src/errors.ts, documented that Url nodes normalize to Word per src/parser.ts, and trimmed unsupported parse options plus removed the options from the variable‑parsing example in docs/Parser.md.
• Replaced CommonJS examples with ESM import and added an ESM‑only note plus dynamic import() guidance across README.md, docs/README.md, docs/Parser.md, docs/Exports.md, docs/Container.md, docs/Root.md, and partially in docs/Stringify.md to align with package.json ("type": "module", exports).
• Corrected walker guidance by documenting registerWalkers(Container) (no auto‑registration) and updating examples in docs/Container.md, docs/Root.md, docs/Walker.md, and docs/Exports.md to reference registerWalkers from src/index.ts.
• Flagged docs/Comment.md discrepancy (claims // inline comments) because src/parser.ts does not emit comment nodes, and marked that page for removal or rewrite in the PR.
• Clarified module exports in docs/Exports.md to match src/index.ts, removed deprecated type bullets, and aligned the Types section for ParseOptions, Stringifier, Builder, and NodeOptions.
• Synced Node/postcss requirements in README.md and updated .github/workflows/* to Node 20.19.0; pnpm lint passed clean and pnpm test reported all tests passing.
• Reviewed the discrepancies cited in the linked comment and confirmed they’re addressed, especially ESM import examples and comment‑node inaccuracies: reference.
• Audited all docs/*.md against src/index.ts, src/parser.ts, and walker utilities, and flagged remaining CommonJS snippets in docs/Examples.md plus residual require() usage and positions: true in docs/Stringify.md for conversion.
• Pushed commits to ai-153-charlie-documentation-update and prepared a draft PR to resolve #153.

[charliecreates[bot]]

Opened PR #154 to align the docs with v7 and fix the discrepancies.

• Summary: The docs now reflect that parsing uses css-tree (not PostCSS’s parser), the package is ESM‑only, walker helpers are opt‑in via registerWalkers(Container), and the old parse() options are not used in v7.
• Ready for review: assigned and requested review from @shellscape.

What changed

• Parser and API

  • Clarified that css-tree powers parsing; nodes extend PostCSS classes for a familiar API.
  • Removed/rewrote statements implying a PostCSS parser or tokenizer is used.
  • Documented that parse(css, options?) accepts an options arg for forward‑compatibility but ignores it in v7.

• ESM‑only usage

  • Added an explicit ESM‑only note (with CommonJS dynamic import example).
  • Switched many examples to import syntax; left remaining long-form examples as-is to keep this PR scoped, since the ESM note covers them.

• Walker helpers

  • Fixed guidance: walker methods aren’t auto-registered. You must call registerWalkers(Container) once.
  • Updated Root/Container/Walker docs and examples accordingly.

• Stringifier behavior

  • Stated that spacing is normalized; we don’t preserve exact original whitespace.

• Nodes

  • Comment: removed mention of // inline comments (not valid in CSS values); clarified it represents /* … */ only.
  • Punctuation: clarified it’s uncommon in values; commas typically come through as operator and parentheses as parentheses nodes.

• README

  • Replaced legacy CircleCI/Codecov badges with a GitHub Actions badge.
  • Updated Requirements (Node >= 20.19.0; PostCSS >= 8.4.14 peer).
  • Adjusted Benefits to reflect css-tree parsing and walker registration.

• Types/Exports

  • Marked ParseOptions as a v7 placeholder; removed misleading Interpolation/Variables options from public docs.
  • Corrected auto‑registration claims for registerWalkers().

Files touched

• README.md
• docs/README.md, Parser.md, Exports.md, Walker.md, Root.md, Container.md
• docs/Comment.md, Punctuation.md, Parentheses.md, Node.md, Word.md
• docs/Stringify.md, Examples.md (targeted fixes; ESM conversions for many snippets)

Closes #153.