Skip to content

docs: README and user pages open with the reader's gain - #140

Merged
leemour merged 3 commits into
mainfrom
docs/readme-openings
Nov 17, 2026
Merged

leemour merged 3 commits into
mainfrom
docs/readme-openings

Conversation

@leemour

@leemour leemour commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Why

The owner keeps sending pages back for their openings. This brings the README and every user page to the WireCat opening order (cli-docs AUTHORING.md, "Mandatory opening order") and the README to tg-cli's shape (WC-DOC-7), in the register of amo's new README.

What

  • README rewritten after tg-cli: hero promise, three benefits, "What you get" with an illustrative You/Agent dialogue, "Why b24" from the comparison, quick start, agents, what it can do (deals and leads, the funnel, contacts, calls, the morning digest, activities, any method), how it works, permissions, limits, security, help.
  • Every user page opens with the reader's gain, then the problem, what the agent or reader gets, the tools and the one prerequisite, then **On this page:** as a numbered list. The glossary blocks in calls and permissions are folded into prose.
  • New headings so the list has targets: index, installation, configuration, troubleshooting and security. Existing anchors are kept. The ru and es translations in cli-docs need the same structure at the next sync.
  • usage.md gets "What changed" for changes list and its --format report morning digest.
  • commands.md intro changed in scripts/commands.ts, regenerated.
  • Fixed facts: a first sync copies the webhook employee's deals and leads (the README said it copied nothing), the REST API plan line follows Bitrix24's page, and runnable sign-in commands use example values, not placeholders (WC-DOC-12).

No changelog fragment: docs only.

Testing

  • pnpm docs:check (links, anchors, cspell, rumdl, markdownlint) and pnpm generate:check pass.
  • Bare b24 work setup ran in an isolated temp folder and printed the webhook steps.
  • changes list --format report ran against the test harness and printed a morning-digest report.

Follow-up (rebased on main)

  • Leak check: the README's contact example used a phone-like number that security:no-leak refused. It gives an example e-mail now.
  • Banner (WC-DOC-21): the social preview, its alt text and the README heading all say "Bitrix24 CRM CLI for AI agents", as tg-cli does. The repository's social preview needs a manual upload of docs/images/social-preview.png (Settings → General → Social preview).
  • Voice: no semicolons in the user pages.
  • GitHub page: new description; topics add codex and bitrix24-api and keep wirecat.
  • The README keeps tg-cli's section order (why before quick start) rather than the literal WC-DOC-7 example order, to match tg and amo.
  • pnpm release:check passes locally.

🤖 Generated with Claude Code

leemour and others added 3 commits November 17, 2026 11:21
…README shape

The README now follows tg-cli's structure: a centered hero with a one-paragraph promise, three benefits,
"What you get" with an illustrative You/Agent dialogue, "Why b24" from the comparison page on wirecat.dev, then
quick start, agents, what it can do (deals and leads, the funnel, contacts, calls, the morning digest, activities,
any method), how it works, permissions, limits, security and help.

Every user page opens in the WireCat order: what the reader gains, then the problem behind it, what the agent or
reader can then do, the tools involved and the one prerequisite, and an "On this page" list before the steps. The
glossary blocks of calls and permissions are folded into the prose. Troubleshooting and security get section
headings so the list has places to point to, and usage gets a "What changed" section for changes list and its
morning digest. The commands page intro changes in the generator's text.

Facts corrected on the way: a first sync copies the webhook employee's deals and leads (it did not copy nothing),
and runnable sign-in commands use example values instead of placeholders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…colons

- README's contact example used a phone-like number that the no-leak check
  (security:no-leak) refuses. It now gives an example e-mail address instead.
- The social preview, its alt text and the README heading now say the same
  thing, "Bitrix24 CRM CLI for AI agents" (WC-DOC-21, as tg-cli does). The
  image was made the same way as before, from the shared HTML banner with
  headless Chrome at 1280x640.
- User pages no longer use semicolons, per the public writing voice. Each
  one became a full stop, or a comma inside a code comment. Code, JSON and
  generated commands.md are untouched (WC-DOC-4).

Runnable commands keep the example values from the previous commit
(WC-DOC-12). pnpm release:check passes locally.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour force-pushed the docs/readme-openings branch from c85e887 to 04a9b71 Compare November 17, 2026 10:24
@leemour
leemour merged commit dbc6f8c into main Nov 17, 2026
17 of 18 checks passed
@leemour
leemour deleted the docs/readme-openings branch November 17, 2026 10:30
@leemour leemour mentioned this pull request Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant