docs: README.md updates

Author: cmath10

packages/conventional-bump/README.md

@@ -0,0 +1,84 @@
+# @modulify/conventional-bump
+
+Semantic-release helper that analyzes conventional commits and recommends the next version (major/minor/patch)
+based on your git history.
+
+- Repository: https://github.com/modulify/conventional
+- Spec: https://www.conventionalcommits.org/en/v1.0.0/
+
+## Installation
+
+- npm: `npm i @modulify/conventional-bump`
+- yarn: `yarn add @modulify/conventional-bump`
+- pnpm: `pnpm add @modulify/conventional-bump`
+
+## Quick start
+
+```
+import { ReleaseAdvisor } from '@modulify/conventional-bump'
+
+const advisor = new ReleaseAdvisor()
+const recommendation = await advisor.advise()
+
+if (recommendation) {
+  console.log(recommendation.type)   // 'major' | 'minor' | 'patch'
+  console.log(recommendation.reason) // human–readable explanation
+}
+```
+
+## Public API
+
+### Types
+
+- `type ReleaseType = 'major' | 'minor' | 'patch'`
+- `type ReleaseRecommendation = { type: ReleaseType; reason: string }`
+- `type CommitType = { type: string; section: string; hidden?: boolean }`
+
+### ReleaseAdvisor
+
+Creates an analyzer that reads commits from git and recommends the next semantic version.
+
+Constructor:
+
+```
+new ReleaseAdvisor(options?: {
+  cwd?: string;         // Working directory for git commands
+  git?: Client;         // Custom @modulify/conventional-git client (for tests)
+  parse?: ParseOptions; // Conventional commit parser options (@modulify/conventional-git)
+  types?: CommitType[]; // Custom type-to-section mapping
+})
+```
+
+Method:
+
+```
+advise(options?: {
+  ignore?: (commit: Commit) => boolean; // Skip specific commits
+  ignoreReverted?: boolean;             // Ignore commits that were later reverted (default: true)
+  preMajor?: boolean;                   // If true, downgrade major→minor and minor→patch for <1.0.0
+  strict?: boolean;                     // If true, return null when there are no meaningful changes
+}): Promise<ReleaseRecommendation | null>
+```
+
+Behavior highlights:
+- Breaking changes ("!" or notes) lead to `major` unless `preMajor` is enabled.
+- New features (`feat`/`feature`) lead to `minor`.
+- Otherwise, `patch` is recommended when there are other visible changes; with `strict: true` and no changes, returns `null`.
+- With `ignoreReverted: true` the advisor cancels out commits that were reverted later, including revert-of-revert chains.
+
+## Example: pre-1.0.0 workflow
+
+```
+const advisor = new ReleaseAdvisor()
+const next = await advisor.advise({ preMajor: true })
+console.log(next?.type) // 'minor' or 'patch' for <1.0.0 projects
+```
+
+## Example: strict mode
+
+```
+const next = await advisor.advise({ strict: true })
+if (!next) {
+  console.log('No release-worthy changes since last tag')
+}
+```

packages/conventional-changelog/README.md

@@ -0,0 +1,60 @@
+# @modulify/conventional-changelog
+
+Generate a changelog from your git history using conventional commits.
+Groups entries by sections you define and skips commits that were reverted later.
+
+- Repository: https://github.com/modulify/conventional
+- Spec: https://www.conventionalcommits.org/en/v1.0.0/
+
+## Installation
+
+- npm: `npm i @modulify/conventional-changelog`
+- yarn: `yarn add @modulify/conventional-changelog`
+- pnpm: `pnpm add @modulify/conventional-changelog`
+
+## Quick start
+
+```
+import { ChangelogWriter } from '@modulify/conventional-changelog'
+
+const writer = new ChangelogWriter({
+  types: [
+    { type: 'feat', section: 'Features' },
+    { type: 'fix', section: 'Bug Fixes' },
+  ],
+})
+
+const content = await writer.write()
+console.log(content)
+```
+
+You can also pass a Node.js Writable to stream the generated content:
+
+```
+import { createWriteStream } from 'node:fs'
+
+const out = createWriteStream('CHANGELOG.md')
+const writer = new ChangelogWriter({ output: out, types: [...] })
+await writer.write()
+```
+
+## Public API
+
+### ChangelogWriter
+
+Constructor:
+
+```
+new ChangelogWriter(options?: ChangelogOptions)
+```
+
+Method:
+
+```
+write(): Promise<string>
+```
+
+Behavior highlights:
+- Groups commits into sections according to `types`.
+- Skips commits that were later reverted; revert-of-revert chains are handled so that original commits are restored.
+- When `output` is provided, the same content is written to the stream and also returned as a string.

packages/conventional-git/README.md

@@ -1 +1,64 @@
-# @modulify/conventional-git
+# @modulify/conventional-git
+
+Thin wrapper over git that adds conventional-commit parsing and semantic tag helpers.
+
+- Repository: https://github.com/modulify/conventional
+- Spec: https://www.conventionalcommits.org/en/v1.0.0/
+
+## Installation
+
+- npm: `npm i @modulify/conventional-git`
+- yarn: `yarn add @modulify/conventional-git`
+- pnpm: `pnpm add @modulify/conventional-git`
+
+## Quick start
+
+```
+import { Client, packagePrefix } from '@modulify/conventional-git'
+
+const git = new Client()
+
+// Read parsed commits (async iterable)
+for await (const c of git.commits()) {
+  console.log(c.type, c.scope, c.subject)
+}
+
+// Get semver tags (async iterable)
+for await (const t of git.tags({ clean: true })) {
+  console.log('tag:', t)
+}
+
+// Get latest version from tags
+console.log(await git.version())
+
+// Work with package-scoped tags
+const prefix = packagePrefix('my-package') // => 'my-package@'
+for await (const t of git.tags({ prefix, clean: true })) {
+  console.log('my-package version:', t)
+}
+```
+
+## Public API
+
+### Functions
+
+- `packagePrefix(packageName?: string): string | RegExp`
+  - Returns a prefix for package-specific semver tags. If no name is provided, returns a RegExp that matches any `<name>@` prefix.
+
+### Client
+
+Constructor:
+
+```
+new Client(options?: { cwd?: string; git?: GitClient })
+```
+
+Properties:
+* `git` — access to the underlying low-level client.
+
+Methods:
+
+* `commits` – Returns async iterable of parsed conventional commits.
+* `tags` – Streams semver tags. When `prefix` is provided, only tags with that prefix are considered.
+  `skipUnstable` skips prereleases. With `clean: true`, the returned items are cleaned versions (e.g. `1.2.3`).
+* `version` – Returns the latest semantic version (sorted with semver) or `null` when no semver tag is found.