Chukke documentation
Workspaces and Files
Understand workspaces, individually opened documents, Open Editors, and Recent Files.
A Chukke workspace is a folder you select. Chukke works with the files in place and does not import the folder into a cloud workspace. You can also open an individual supported document outside the active workspace without moving or importing it.
Supported documents
The workspace tree shows Markdown and text documents with these extensions:
.md.markdown.txt
Supported files remain visible when their names begin with ., and Chukke shows ordinary dot-directories such as .github. Repository metadata and Chukke internals such as .git, .hg, .svn, .chukke, .DS_Store, and Chukke’s transient files stay hidden.
Generated dependency, cache, and build folders are hidden by default. Chukke recognizes high-confidence output from Cargo/Tauri, Maven, Node/Electron/Vite, Android/Gradle, Python, Swift Package Manager, .NET, CMake, and Flutter/Dart by checking bounded filesystem markers. It never runs project tools or code while opening a repository. Ambiguous names such as target, build, dist, out, bin, and obj remain visible unless matching project evidence identifies them as generated, so an authored target/goals.md is not hidden merely because of its folder name. When generated folders are detected, use Show or Hide in the Files footer. This choice lasts only for the current workspace session, and hiding a generated folder does not close a document that is already open below it. Unsupported files such as .env are not shown in the Markdown-first tree.
Chukke opens and saves regular UTF-8 documents up to 10 MiB. File Explorer loads one folder at a time instead of scanning the complete repository before opening it. One displayed directory may contain up to 20,000 immediate entries, and a requested path may be up to 64 levels deep. Unsupported files still count while that directory is inspected. A folder with too many entries shows a branch error and Retry. A folder beyond the depth limit shows a branch error without Retry, since another attempt cannot change its depth. The workspace and other loaded branches remain available. Symbolic links, FIFOs, sockets, devices, and other special entries are not traversed or shown.
Chukke watches the selected workspace for files and folders created, renamed, moved, or removed by Git, Finder, editors, and other local tools, then refreshes the root and folders File Explorer has already loaded. Repository-scale workspaces and generated dependency or build trees do not require one watcher handle per entry. Monitoring remains limited to the folder you selected. Hidden internal or generated-subtree changes do not trigger File Explorer refreshes until generated folders are shown.
You can open, create, copy, rename, and move supported files and folders, including moving them to Trash. Native workspace commands are accepted only for the active workspace selected in Chukke, and preflight commands are accepted only for the pending workspace you just authorized. Workspace operations stay anchored to that folder even if another local process replaces a descendant with a symbolic link while an operation is running. Successful copies, file renames, moves, and Trash moves provide an eight-second Undo action. With focus outside an editor or text field, Cmd+Z or Ctrl+Z runs the latest available file-operation undo; text-editing undo retains priority while you are typing. Move conflicts never overwrite the destination, keep the move dialog open, and identify the existing-name conflict.
The File menu provides the same routes as the corresponding workspace controls: New Folder…, Recently Trashed…, Open Workspace in Finder, and Show Active Document in Finder. Windows labels these locations File Explorer, while Linux uses File Manager. New folders are created in the selected folder, the active workspace document’s folder, or the workspace root, in that order. Recently Trashed… is also available on Welcome for personal-template recovery; inside a workspace, it additionally includes authorized files and templates from that workspace. The two location commands reveal the workspace root or the active workspace or individually opened document without changing it.
To copy a file or folder, open its File Explorer context menu and choose Copy, then choose Paste from a destination folder or the workspace heading. You can also choose Copy to… and select the destination directly. With File Explorer focus, Cmd+C stores the focused file or folder as a Chukke-only session reference. Cmd+V pastes into the focused folder, the parent of a focused file, or the workspace root when its heading has focus. The regular macOS clipboard is not changed, and editor text copy and paste continue to work normally.
Direct file copies support the visible .md, .markdown, and .txt documents up to the 10 MiB document limit. A folder copy preserves its entire real directory tree, including files that Chukke does not display. One folder copy can inspect at most 20,000 total entries and 64 folder levels, with at most 50 MiB for one contained file and 500 MiB across the complete tree. Internal, generated, hidden, unsupported, and dot-directory descendants all count and are copied for this explicit complete-folder operation, regardless of the current generated-folder visibility. Chukke checks the complete source before publishing the destination, verifies the completed copy before offering success, and removes a caught partial copy. Chukke never overwrites, merges, or automatically renames a destination: exact and case-only name conflicts fail, and pasting into the source’s current parent is unavailable. A folder cannot be copied into itself or a descendant, and symbolic links or special files anywhere in a copied folder are rejected.
The copied item keeps its original name and is not opened automatically. Copying does not change tabs, Recent Files, Context Pack selections, or local history. For eight seconds, the success message provides Undo and the same action works with Cmd+Z or Ctrl+Z while focus is outside an editor or text field. Undo removes only the most recent copy when the source and complete destination are still unchanged. If either side was edited, replaced, renamed, removed, or has unsaved destination changes, Chukke refuses the undo and preserves the copied content.
The session source remains available for pasting into more folders until you switch or close the workspace, rename or relocate the source, or move it to Trash. If the source file, or any open document inside a source folder, has unsaved changes, Chukke asks whether to copy the last saved version and never saves or copies the editor buffer automatically.
Moving a file or folder to Trash requires confirmation. Cancel receives initial focus, and pressing Escape cancels the action. If a file has unsaved editor changes, the confirmation warns that those changes will be discarded and Trash will contain the last saved version. Folder confirmation covers the complete folder, including files Chukke does not display and unsaved changes in open descendants. Chukke delegates the actual move to macOS and never falls back to permanent deletion. For eight seconds, the success message provides Undo and the same action works with Cmd+Z or Ctrl+Z outside editors and text fields. Undo restores only the exact item macOS moved and refuses to overwrite an occupied original location or restore a changed Trash item. Afterward, open Recently Trashed from the Files toolbar to restore a Chukke Trash move, even after restarting the app. Chukke refuses to overwrite an occupied original location or restore a changed Trash item. The list holds up to 50 recent moves; older recovery records may drop off sooner when Chukke’s metadata reaches its 1 MiB limit. This never removes the items from macOS Trash. Remove from list deletes only Chukke’s recovery record and leaves the item in macOS Trash. Finder’s Put Back may also be available. Existing bounded Chukke History is preserved.
Choose Open File… to open a supported document outside the active workspace, or use Chukke through Finder’s Open With menu. Finder owns the Open With and Change All choices. Chukke registers as an alternate editor but does not change the default application itself.
An individually opened document supports editing, formatting, undo and redo, Edit, Split, Preview, Find, Outline, Review, Insights, Model-ready, Assist, Refine, Save, Save As, export, and Reveal in Finder. It deliberately does not receive workspace history, workspace-tree file actions, templates, workspace dictionary changes, or Context Pack membership.
For workspace documents, File → Save As… creates another Markdown or text file inside the active workspace and keeps overwrite review inside Chukke. Use File → Export → Markdown… when you want to write a copy of a workspace document outside the workspace.
Saving an individually opened document into the active workspace through Save As… converts its tab to a workspace document after the write succeeds. Saving elsewhere keeps it as an individual document.
Open Editors and the workspace tree
Open Editors is the current-session list of all open workspace and individual documents in tab order. The workspace tree is different: it shows only the contents of the active workspace.
Chukke uses compact path context and a full-path tooltip when individual documents or duplicate names need disambiguation. The path is for local recognition only.
Access after relaunch
The Mac App Store build stores an app-scoped security bookmark for a recent workspace. This lets Chukke request access to the same user-selected folder after relaunch while remaining inside the macOS App Sandbox.
If a folder moved, was deleted, became inaccessible, or needs authorization again, Chukke asks you to resolve or reselect it. Canceling reauthorization preserves the current workspace.
The Mac App Store build uses the same app-scoped bookmark mechanism for Recent Files. Reopening a moved or unauthorized file may ask you to locate it again. Canceling leaves the current session unchanged.
Workspace content and application data
User-owned content includes your workspace documents, intentional workspace templates under .chukke/templates, and editable personal templates. Workspace content remains in the folder you control; personal templates live in Chukke’s macOS application-data container but remain yours and are never part of app cleanup.
Application-owned data includes settings, recent-workspace and recent-file bookmarks, local history, and sanitized diagnostics. These live in Chukke’s macOS application-data container and can be cleared only through their relevant fixed-scope controls.
Templates and Context Pack
The Template Library combines read-only built-in templates, editable personal templates, and workspace templates stored under .chukke/templates. One refresh inspects at most 1,000 directory entries, loads at most 200 template files, accepts at most 1 MiB per template and 20 MiB across the personal and workspace library, and bounds malformed-file warnings. Template frontmatter is limited to 256 KiB, 100 top-level fields, and bounded nesting, aliases, and values before YAML parsing. Excess or malformed templates are skipped while valid in-budget templates remain available. Chukke applies the same 1 MiB item limit when saving an editable template.
Template preview links stay within Chukke’s link controls: web links open in your default browser, section links stay in the preview, and relative document links require opening the created document first. A preview link never navigates the Chukke window to a website.
Context Pack scans for workspace .md, .markdown, and .txt documents only when you open the builder. The recursive scan may inspect up to 100,000 entries across 64 folder levels because real repositories often contain many source, asset, and configuration files before the relevant documents are found. It follows the current generated-folder visibility. If the scan exceeds either bound or encounters a traversal failure, Chukke shows an explicit error and no partial document list; use Retry after narrowing or correcting the workspace.
When you choose Move to Trash for a personal or workspace template, Manage Templates stays in place behind the confirmation. Canceling returns you to the same list position. Confirming moves the template’s Markdown file to macOS Trash and provides an eight-second Undo action. Afterward, open Manage Templates → Recently Trashed to restore personal templates or templates from the active workspace. The Files toolbar opens the same recovery list, including workspace files. Finder’s Put Back may also be available. Creating a document from a template and adding files to Context Pack require an active workspace. Individually opened documents are not added to Context Pack.
Workspace template folders must stay inside the selected workspace. Chukke rejects symbolic links at .chukke or .chukke/templates and leaves those user-owned entries untouched.
Context Integrity
To check repeated or potentially conflicting instructions, open a folder’s File Explorer context menu and choose Check Instruction Consistency. The workspace heading checks Entire Workspace; a subfolder check displays Selected Folder and its workspace-relative path. In the right-dock review, choose Entire Workspace to expand a selected-folder check, or Check again to repeat the current scope. The check runs only when requested and never changes a document.
Context Integrity examines .md and .markdown files under that scope, including ordinary instruction folders such as .github and .claude. It uses the current editor buffer for an open workspace file, including unsaved text; other files are read from disk. Generated content, dependencies, symbolic links, and special files are excluded. Individually opened documents outside the workspace are not included.
The review groups exact duplicates, near duplicates, command drift, numeric drift, and possible conflicts, with counts for each group. Permission and negation conflicts keep distinct labels within possible conflicts. Near duplicates alone show a whole-number text similarity percentage, calculated locally from the two instructions’ normalized character sequences. It measures lexical overlap, not confidence, semantic agreement, or whether the rules apply together. Each finding shows both file paths, source lines, excerpts, and relevant scope information. A repeated rule may be intentional, and a possible conflict is a prompt for human review rather than proof that one file is wrong. Click a source location to open it at that line. If a source changes, refresh the check before relying on its old location. Context Integrity does not change Model-ready scores or use Assist.
One check may inspect at most 20,000 directory entries and 64 folder levels, analyze at most 128 files of 1 MiB each and 16 MiB combined, and has bounded instruction, comparison, finding, and time budgets. Analysis complete appears only when the requested scope was fully analyzed. If a file cannot be analyzed or a limit is reached, Analysis incomplete names the reason and shows analyzed and skipped counts. Findings from verified files can still appear, but the scope has not been cleared. Cancellation discards findings; changed sources make results stale. A complete check with no findings means only that this deterministic checker found none in the analyzed scope; it cannot prove the absence of every natural-language contradiction.
Recents
Recent Workspaces stores authorization information for folders you previously selected. Recent Files stores at most 10 individually opened documents and exposes them on Welcome and under File > Open Recent > Files.
Removing one entry or clearing either list deletes only Chukke’s saved authorization metadata. It never deletes a folder or document. Open Editors is not a recent-history list and lasts only for the current session.
Backup considerations
Continue using Git, Time Machine, or another backup workflow for important work. Chukke’s local history is a bounded recovery feature, not a replacement for a complete backup.