docs: add tty docs section with API reference

[dreyfus92]

What does this PR do?

adds tty docs section

Type of change

• Typo
• New Documentation for Feature
• Improvement for Clarification
• Chore (dependencies, CI, tooling)

AI-generated code disclosure

• This PR includes AI-generated code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	bombshell-docs	27a4328	Commit Preview URL Branch Preview URL	Jul 09 2026, 03:40 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	bombsh-docs-router	27a4328	Commit Preview URL Branch Preview URL	Jul 09 2026, 03:38 AM

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​bomb.sh/​tty@​0.8.0
	mermaid@​11.16.0
	astro-mermaid@​2.1.0

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm mermaid is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: package.json → npm/mermaid@11.16.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/mermaid@11.16.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm robust-predicates is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: pnpm-lock.yaml → npm/mermaid@11.16.0 → npm/robust-predicates@3.0.3 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/robust-predicates@3.0.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[cowboyd]

This talks about the different apis, but I think we should also invest in explaining the archictecture as laid out in the README https://github.com/bombshell-dev/tty/blob/main/README.md which addresses the why the apis are laid out the way they are.

[cowboyd]

Is this correct, or an artifact of using starlight as a basis

[dreyfus92]

yeah this is correct, the docs site runs on starlight so Aside is a component from their internal lib, it's what renders the callout boxes, not leftover scaffolding. there's also the :::note directive syntax that doesn't need the import if we'd rather keep pages import-free.

[cowboyd]

what is twoslash vs typescript ?

[dreyfus92]

ts is just syntax highlighting, twoslash runs the snippet thru the actual ts compiler at build time via the twoslash-ec plugin for expressive code so you get editor-style hover info in the rendered docs, and the build fails if an example stops typechecking. basically makes every code block a verified example, so when you hover you see the type definitions.

[dreyfus92]

thanks for the review @cowboyd

This talks about the different apis, but I think we should also invest in explaining the archictecture as laid out in the README https://github.com/bombshell-dev/tty/blob/main/README.md which addresses the why the apis are laid out the way they are.

i will try to explain the architecture within the getting started doc in and i'll circle back 😄 if you prefer to have a dedicated route/doc for it let me know 👀