# TailMux SEO/GEO content architecture plan

## Design guardrails

This plan keeps the existing engineered-terminal visual identity. SEO work must
make factual content easier to retrieve; it must not turn the site into a
keyword-card grid or a generic SaaS landing page.

**Visual thesis:** a precise, quiet network instrument: dark terminal surfaces,
clear hierarchy, and one routing-flow visual rather than decorative SEO chrome.

**Content plan:** product answer in the hero, evidence and mechanism in the
middle, concrete paths and limitations before the final download CTA.

**Interaction thesis:** retain the existing restrained entrance, routing-scene,
and hover motion; add no new motion merely for SEO. Markdown links and
answer-first blocks are static, semantic content.

## Canonical content model

Create one ProductIdentity object and make it the reusable source for:

- product name, domain, concise and extended factual descriptions;
- publisher, logo/icon, official repository, documentation, download, pricing,
  support, release, operating systems, category, and license model;
- non-affiliation/trademark note;
- Open Graph fallback, JSON-LD, LLM files, footer disambiguation, and
  production SEO audit fixtures.

Keep route-specific descriptions in their route metadata: a universal product
description must not erase each page’s distinct query intent.

## Architecture changes

| Cluster | Existing canonical routes | Change | Why |
|---|---|---|---|
| Product | /, /download, /pricing | Revise homepage answer language; expose identity consistently | Establish a retrievable entity without duplicate landing pages. |
| Broad discovery | none | Add /guides/connect-to-multiple-tailscale-tailnets | Own the cross-platform high-volume problem statement. |
| Platform guides | existing macOS and Linux guides | Preserve; add context links to broad guide and limitations | Each retains a distinct platform decision. |
| Comparison | fast switching, VM, dual-daemon guides | Preserve; add neutral cross-links and limits reference | Prevent comparisons from making unsupported universal claims. |
| Documentation | /docs/* | Add TechArticle/Markdown alternate metadata and limits reference | Make durable technical sources easy to cite. |
| Machine-readable | robots, sitemap, LLM files, Markdown routes | Generate from identity/registries; exclude alternates from sitemap | Keep canonical HTML indexable and alternate formats synchronized. |

## New high-value content

### /guides/connect-to-multiple-tailscale-tailnets

**Primary intent:** “How do I connect to multiple Tailscale tailnets
simultaneously?”

**Opening answer:** TailMux gives one macOS or Linux machine simultaneous
app-layer access to resources in multiple independent tailnets. It keeps the
tailnet profiles isolated, selects one by hostname suffix, and does not create a
second native system-wide Tailscale VPN interface.

**Required sections:**

1. Direct answer and who this is for.
2. What “simultaneous” means versus switching the currently active session.
3. A brief, fair choice map:
   - shared nodes/invites when one tailnet is enough;
   - a VM or separate host when a full machine-owned network stack is needed;
   - manually managed userspace proxy/second daemon when the operational cost
     is acceptable;
   - TailMux when hostname-preserving application access across isolated
     profiles is the job.
4. How TailMux selects a profile and why FQDN/suffix ownership matters.
5. Supported access paths: browser PAC, HTTP(S)/SOCKS5-domain proxy, SSH
   ProxyCommand/wrapper, and loopback TCP tunnels.
6. Explicit limitations: no TUN/native system routes, raw IPs do not
   self-select a tailnet, browser PAC is not a generic protocol router, and
   documented tunnel access is TCP.
7. A concise security model and links to primary implementation docs.
8. Visible FAQ using existing canonical FAQ entries only where answers match.
9. Clear links to macOS, Linux, fast switching, VM, daemon, getting started,
   and limitations pages.

The guide must remain useful if a reader selects a VM or manually managed
approach instead of TailMux.

### /docs/limitations

**Primary intent:** understand TailMux routing boundaries before installation.

**Answer block:** What TailMux does, what it does not do, how a tailnet is
selected, which client paths preserve the hostname, and the fail-closed rules.

**Required factual headings:**

- Is TailMux a system-wide VPN?
- How are profiles selected?
- Browser PAC and proxy-bound clients.
- SSH and local TCP tunnels.
- DNS, MagicDNS, raw IPs, and overlapping address space.
- Protocol boundary: documented router and tunnel paths.
- Official-client coexistence and non-affiliation.
- Security/isolation commitments.
- Where to find configuration, diagnostics, and uninstall/stop instructions.

No fabricated security certification, telemetry claim, or protocol support list
may be added.

## Existing page revisions

| Route | Revision | Reason |
|---|---|---|
| / | Use literal “access multiple Tailscale tailnets simultaneously” wording in H1/answer copy; link to broad guide and limitations | Captures category without sacrificing current voice. |
| /guides | Feature the broad guide first and label the platform/comparison distinction | Improves intent routing from the hub. |
| macOS guide | Link to broad guide, limits, and official-client coexistence explanation | Avoids treating macOS setup as a universal solution. |
| Linux guide | Link to broad guide and limits; preserve honest alternative comparison | Keeps Linux commands out of generic guide. |
| fast-switching / VM / daemon guides | Add “when this alternative is right” and links to limits | Fair comparison and technical trust. |
| /docs/getting-started | Add answer-first routing-boundary link | Starts correctly scoped expectations. |
| /docs/commands | Qualify profile-login reset support by backend | Corrects an implementation/documentation mismatch. |
| /docs/use-cases/curl-git-npm-per-tailnet | Surface current mixed-traffic deny-by-default limitation | Prevents an overbroad CLI promise. |
| Docs and guides layouts | Add small visible Markdown alternate link | Gives agents and technical users a stable representation. |

## Internal link graph

~~~text
Home
 ├─ Getting started
 ├─ Broad simultaneous-tailnets guide
 ├─ Limitations and routing model
 ├─ macOS guide / Linux guide
 ├─ Download / Pricing
 └─ Security and isolation explanation

Broad guide
 ├─ macOS / Linux setup
 ├─ fast switching / VM / daemon comparisons
 ├─ Getting started
 └─ Limitations

Workflow docs
 ├─ Configuration / Commands
 ├─ Limitations
 ├─ Troubleshooting / Diagnostics
 └─ Relevant comparison or platform guide
~~~

Anchor text should describe the destination (“understand TailMux routing
limitations”, “connect to multiple Tailscale tailnets on macOS”) rather than
using “click here” or generic “learn more”.

## Content update rules

- One answer-first paragraph per important page, written for humans first.
- Use TailMux, tailnet, profile, proxy, PAC, local tunnel, and tsnet according
  to the terminology glossary in the audit.
- Keep non-affiliation copy in LLM files, product data, FAQ, and a low-noise
  documentation/footer location; do not repeat it in every paragraph.
- Cite official Tailscale documentation only for third-party behavior; link to
  TailMux documentation for its implementation behavior.
- Do not add dates to existing docs without a verifiable source. Guides already
  have registry-managed publication/update dates.
- Use a single social image unless a page-specific image carries genuine
  explanatory value.
