Overview

Documentation inventory for the hierarchical workspace

This is the issue #61 review record for the model deployed by issues #49–#59. It records which current pages were reviewed, what changed, and which pages remain intentionally historical or domain-neutral.

Current product vocabulary

Folder is the general entity. A Root Folder has no parent. A subfolder is a folder described relative to its parent.
Folder paths are navigation aids. UUIDs are stable identifiers.
Every active member has one private, non-archivable default Root Folder, initially named My Files, and may create additional roots.
Subfolders have immutable root identity, a maximum depth of 32, sibling-scoped case-insensitive names, cycle prevention, same-root moves, and empty-only archive.
Groups are user-owned and organization-local. Roles are owner, manager, and member; membership begins only after invitation acceptance.
Folder grants are additive, inherit through descendants, and have no deny rule. Administrators have organization-wide access without implicit ownership or grants; overrides are audited.
Metadata means administrator-defined typed fields. Tags are user-managed name=value pairs with separate current-state and append-only revision tables.

Reviewed current pages

Page	Review result
`docs/README.md`	Changed: links this inventory and the current documentation map.
`docs/glossary.md`	Changed: canonical folder, default, subfolder, group-role, inherited-access, metadata, tag, and audit definitions.
`docs/SITE_HANDOFF.md`	Reviewed; retained as site implementation handoff, not product behavior authority.
`docs/AGENTS.md`	Reviewed; retained as documentation-local agent guidance.
`docs/product/overview.md`	Changed: current hierarchical workspace and sharing model.
`docs/product/mvp-scope.md`	Changed: shipped folders, groups, browse/search, metadata, and tags.
`docs/product/brand-reference.md`	Reviewed; unchanged because it contains visual identity, not domain behavior.
`docs/users/getting-started.md`	Reviewed: current sign-in and first-file flow.
`docs/users/quickstart.md`	Reviewed: default root, folder creation, upload, browse, and search examples.
`docs/users/files.md`	Reviewed: upload, lifecycle, versions, browse, subtree search, metadata, tags, and tag filters.
`docs/users/access.md`	Reviewed: inherited user/group grants and live revocation semantics.
`docs/users/automation.md`	Reviewed: current JSON fields, cursors, and stable error codes.
`docs/admins/login.md`	Changed: glossary linkage; login behavior remains current.
`docs/admins/invitations.md`	Changed: distinguishes organization invitations from group invitations.
`docs/admins/users-and-groups.md`	Changed: user-owned groups, invitations, roles, transfer, and explicit admin recovery.
`docs/admins/folders-and-metadata.md`	Changed: roots/defaults/subfolders/lifecycle/browse/search and metadata-versus-tags.
`docs/admins/audit.md`	Changed: administrator override and folder/group/tag audit evidence.
`docs/architecture/overview.md`	Reviewed: current service boundaries.
`docs/architecture/current-state.md`	Reviewed: deployed CLI/backend/database state.
`docs/architecture/domain-model.md`	Changed: folder hierarchy, ownership, defaults, group invitations, metadata, and tag tables.
`docs/architecture/security-and-authorization.md`	Changed: inheritance, delegation ceilings, anti-enumeration, and unconditional audited admin access.
`docs/architecture/audit-and-observability.md`	Reviewed: append-only audit and correlation model.
`docs/architecture/file-lifecycle.md`	Reviewed: immutable content versions plus independent metadata/tag revisions.
`docs/architecture/trust-boundaries.md`	Reviewed; unchanged where boundaries are domain-neutral.
`docs/architecture/distribution-and-updates.md`	Reviewed; unchanged because distribution is independent of folder semantics.
`docs/cli/overview.md`	Changed: current command families, self-service groups, inherited grants, tags, and optional admin reason.
`docs/cli/command-reference.md`	Reviewed as executable command/flag/error authority for folders, groups, browse, search, metadata, and tags.
`docs/cli/installation.md`	Reviewed; unchanged because installation is domain-neutral.
`docs/cli/git-install-and-update.md`	Reviewed; unchanged because checkout updates are domain-neutral.
`docs/cli/releasing.md`	Reviewed: current build/release process.
`docs/cli/agent-skill.md`	Reviewed: installed skill behavior and parity expectations.
`docs/operators/folders01-migration-rollback.md`	Intentionally historical: describes the Project-to-Root-Folder cutover and is labeled as a rollback template.
`docs/operators/deactivation.md`	Reviewed: owner-transfer and group recovery constraints.
`docs/operators/restore-from-archive.md`	Reviewed: current reversible lifecycle.
`docs/operators/reconciliation.md`	Reviewed; upload reconciliation remains applicable.
`docs/operators/incident-investigation.md`	Reviewed: audit-led investigation remains applicable.
`docs/operators/release-rollback.md`	Reviewed: client/application rollback, distinct from irreversible post-migration writes.
`docs/operators/ci-cost-control.md`	Reviewed; unchanged because CI cost policy is domain-neutral.
`docs/operations/readiness.md`	Reviewed: release-readiness gates.
`docs/contributing/documentation.md`	Reviewed: page metadata and generation rules.
`docs/decisions/README.md`	Reviewed: ADR index.
`docs/decisions/ADR-0001-cli-first-mvp.md`	Historical decision retained.
`docs/decisions/ADR-0002-storage-catalog-separation.md`	Historical decision retained; current folder terminology is linked where needed.
`docs/decisions/ADR-0003-immutable-history.md`	Retained; still authoritative.
`docs/decisions/ADR-0004-signed-standalone-distribution.md`	Retained; domain-neutral.
`docs/decisions/ADR-0005-private-cli-credential-file.md`	Retained; domain-neutral.

Historical files under delivery/ are evidence of the model that existed when they were written. They are not rewritten to pretend Root Folders existed earlier. Current pages must link historical terms back to the current glossary.

Embedded and generated guidance reviewed

packages/cli/skill/thalix-vault/SKILL.md
packages/cli/skill/thalix-vault/references/*.md
packages/cli/src/skill/export-chatgpt.ts
packages/cli/src/help.ts
src/routes/-docs-content.generated.ts (regenerated from the reviewed Markdown)

The command reference, help output, embedded skill, and ChatGPT export must describe only implemented commands. Parity is enforced by the documentation and skill-command tests.

Old-to-new automation mapping

Removed Project-era surface	Current surface
`tv project list`	`tv folder list [folder-id]` for one-level browse
`tv admin project list`	`tv admin folder list`
`/api/internal/projects/*`	`/api/internal/folders/*`
`projectId` / `project_id`	`folderId` / `folder_id`
Project-wide flat grant	Folder grant inherited through descendants
Admin-created group membership	User-owned group plus accepted invitation
Typed metadata used for arbitrary labels	Typed metadata plus separate free-form tags

Automation must also account for FolderRecord.parentFolderId, rootFolderId, depth, isDefault, owner projection, browse entries/nextCursor, search withinFolderId/tagFilters, and the removal of old compatibility aliases.

Production migration and publication workflow

Database changes are deployed through the Lovable MCP against project a1c5d3f6-34f7-4839-82f1-a1cad0fba9a5; local Docker is not the production deployment path.

Merge/push the reviewed commit to GitHub main.
Confirm Lovable reports the exact latest_commit_sha; do not publish yet.
Capture hosted IDs, row counts, relationships, audit identities, and any collision preflight required by the migration.
Apply the forward SQL through Lovable MCP query_database as one atomic request.
Read back schema objects, constraints, indexes, RPC signatures, row counts, IDs, relationships, audit timestamps, and append-only triggers.
Exercise the changed behavior through rollback-only hosted transactions. Confirm no verification rows/tokens remain.
Obtain explicit publication approval and invoke Lovable deploy_project.
Smoke the production CLI/API, including ordinary-user anti-enumeration and administrator audit evidence.
Close the issue only after production proof.

Backup and rollback limits

Before a production mutation, confirm the provider backup/PITR position and record the exact pre-migration schema/data inventory. Forward migrations are transactional, but application rollback after new-schema writes may be unsafe. Use the issue-specific rollback runbook/template; never run only selected reverse statements. If a migration request fails, verify whether its transaction rolled back before retrying. After incompatible new writes, prefer a reviewed forward fix unless the rollback inventory proves reversibility.

Post-cutover smoke inventory

The release-assurance run must prove, with two ordinary users and one administrator:

exactly one private default root per active member;
additional roots and nested subfolders;
rename, within-root move, empty-only archive, and explicit restore;
user-owned group creation, invitation acceptance, roles, transfer, and removal;
inherited folder grants and immediate revocation/member-removal effects;
nested file upload, immediate-child browse, subtree search, and keyset cursors;
typed metadata and free-form tag set/list/unset on the same file;
combined --within, --meta, and repeatable --tag search;
administrator organization-wide browse/read/download with adminOverride audit evidence;
ordinary-user non-disclosure of hidden folder/file/tag/metadata names, counts, cursors, and bytes.

Review completion checklist

[ ] Current Markdown pages match this inventory.
[ ] tv help, command reference, Agent Skill, and ChatGPT export are command-parity checked.
[ ] Generated in-app documentation is regenerated.
[ ] Links, page metadata, terminology, docs, credential-leak, and stale-status checks pass.
[ ] Copy-ready examples run against an isolated real stack.
[ ] Production migration order/readbacks/rollback limits are included in the issue #60 evidence ledger.