Knowledge Slug + Router Sync Plan

Goal

Allow Sasha’s Knowledge view to use clean /knowledge/<slug> URLs that deep-link to specific HTML documents, while keeping the existing iframe-based renderer and ?doc= backward compatibility.

---

Constraints & Considerations

• The iframe (/api/docs-content/index.html) already handles internal navigation and posts updates via docs:navigation.
• React Router currently only has / and /session/:id routes inside the authenticated app.
• FileTree uses the doc query param to highlight selections and open preview drawers.
• DocsPanel expects the doc query param and calls api.docsResolve to find the HTML preview URL.
• We must keep existing deep links (?doc=guides/foo.md) working while adding slug-based routing.

---

High-Level Steps

1. Add Router Support

   • Register a dedicated React route for /knowledge/* that renders the same AppContent.
   • Decide on a canonical base (e.g., /knowledge), handling trailing slashes and encoded segments.

2. Map Slug ⇄ Doc Path

   • Derive a helper that converts a slug path segment to the underlying doc reference:
     • If slug ends with .html or .md, keep it.
     • Otherwise assume .md when calling docsResolve.
   • Mirror helper to convert iframe paths (e.g., /api/docs-content/foo/bar.html) into /knowledge/foo/bar.

3. Update DocsPanel Source Resolution

   • Parse both location.pathname and location.search.
   • Prefer /knowledge/<slug> when present; fall back to ?doc= for legacy links.
   • Feed the resolved reference into api.docsResolve and keep existing polling/cache-busting logic intact.

4. Sync Browser URL With iframe Navigation

   • When receiving docs:navigation, strip /api/docs-content/ and .html to get the slug.
   • If the top-level route is not already /knowledge/<slug>, call navigate() with replace: true.
   • Ensure this update preserves query params (notably doc) for backwards compatibility until we drop them.

5. Keep FileTree UX Intact

   • When a Markdown node opens:
     • Continue setting doc=<path> for compatibility.
     • New: navigate to /knowledge/<relative-path-without-extension> (URL-encode segments).
   • When a non-doc node is selected (or the preview closes), clear the slug route back to / (or the last non-knowledge route).
   • On mount, if the route is /knowledge/..., ensure the tree highlights the matching file (derive the doc path from the slug and set selectedMarkdown).

6. Handle Back/Forward / Direct Loads

   • Use a useEffect in AppContent (or DocsPanel) that watches location.pathname.
   • When it matches /knowledge/<slug>, push the equivalent doc param (unless already set) so the FileTree effect fires and opens the preview drawer.
   • When navigating away from /knowledge, optionally clear the doc param.

7. Testing Checklist

   • Deep links: open /knowledge/guides/foo directly → iframe loads correct content.
   • Legacy links: open /?doc=guides/foo.md → auto-redirect or display the doc while keeping slug synced.
   • Internal navigation: clicking links inside the Knowledge sidebar updates the top-level URL and the browser back button walks history.
   • File tree interactions: selecting docs updates both slug + iframe; closing resets to chat route.
   • Mobile Knowledge view still works (menu toggles, breadcrumbs, etc.).

8. Rollout / Docs

   • Update developer docs (e.g., docs/technical/implementation/documentation-system-quick-reference.md) with the new slug behavior.
   • Communicate that /knowledge/... URLs are now shareable and stable.

---

Open Questions

• Should we immediately redirect ?doc= links to /knowledge (301/replace) or keep both indefinitely?
• Do we want hash fragments for headings (future enhancement) or rely on iframe internal anchors?
• Should bookmarks include .md or drop the extension for readability?

---

Next Steps

1. Implement router + helper utilities.
2. Update DocsPanel and FileTree per the above.
3. Run through the testing checklist.
4. Document behavior changes for support/dev teams.