diff --git a/README.org b/README.org
index 982f067..e4a7566 100644
--- a/README.org
+++ b/README.org
@@ -43,6 +43,15 @@ For addressing problem
 ** Workflow
 
 
+** Documentation
+
+- API reference: [[file:doc/api-reference.org]]
+- Complete design doc: [[file:doc/design-full.org]]
+- Usage guide: [[file:doc/usage.org]]
+- Installation guide: [[file:doc/installation.org]]
+- Pending issues and features: [[file:doc/pending.org]]
+- Codebase audit notes: [[file:doc/codebase-audit.org]]
+
 ** Example 1
 
 [[doc/eg1.gif]]
diff --git a/doc/api-reference.org b/doc/api-reference.org
new file mode 100644
index 0000000..9694067
--- /dev/null
+++ b/doc/api-reference.org
@@ -0,0 +1,86 @@
+#+TITLE: OCC API Reference
+#+PROPERTY: header-args :tangle no
+
+* Scope
+This file documents the most relevant user-facing and extension-facing
+functions, generic methods, and variables in OCC.
+
+* Entry points (commands)
+- ~occ-run~: Main entry command from ~occ-obj-clock-method.el~, used by keybindings and timers.
+- ~occ-helm-match-select~: Contextual matching selection UI. Uses match-oriented filters and builder.
+- ~occ-helm-list-select~: List/browse selection UI of task candidates.
+- ~occ-helm-list-debug-select~: Selection and action-debug flow.
+- ~occ-helm-list-launch~: Select candidate and then launch action chooser.
+- ~occ-property-edit~: Opens property editor workflow for current context.
+- ~occ-clock-out~: Explicit clock-out wrapper command.
+- ~occ-register-resolve-clock~, ~occ-unregister-resolve-clock~: integration hooks for resolve-clock support.
+
+* Core initialization lifecycle
+- ~occ-initialize~, ~occ-uninitialize~: Bootstraps OCC internals, hooks, and configuration.
+- ~occ-insinuate~, ~occ-uninsinuate~ (used by mode): enable/disable runtime integration.
+- ~occ-collector-default-key~, ~occ-collections-default~: select and resolve active task collection.
+
+* Selection and Helm flow
+- ~occ-obj-select~: Generic entry for interactive candidate selection.
+- ~occ-obj-list-select~: Main selection machinery with configurable filters, actions, prompt, timeout.
+- ~occ-obj-helm-act~ / source-building helpers: Build helm sources from candidates and actions.
+- ~occ-helm-maybe-exit-minibuffer~: Enforces ~selectable~ candidate behavior.
+
+* Ranking and filtering
+- ~occ-obj-calculate-rank~, ~occ-obj-rank-with~: Composite ranking for a task under context.
+- ~occ-obj-rank-inheritable-with~, ~occ-obj-rank-nonheritable-with~: split rank into inherited/non-inherited parts.
+- ~occ-obj-rank-max-decendent-with~: recursive best-descendant ranking; useful for browse display.
+- ~occ-filter-config-initialize~: registers built-in static filters.
+- ~occ-match-filters~, ~occ-list-filters~: default filter pipelines.
+- ~occ-obj-static-to-dyn-filter~: converts static filters to runtime filters with separate display/select closures.
+
+* Property system
+- Property generic interface is centered on ~occ-prop-base.el~ and ~occ-intf.el~.
+- ~occ-obj-impl-get~, ~occ-obj-impl-set~, ~occ-obj-impl-rank~, ~occ-obj-impl-prop=~ are implemented
+  per property symbol in ~occ-property-methods.el~.
+- Built-in context properties include ~currfile~, ~root~, ~git-branch~, and ~subtree~ style logic.
+- Property action generation is handled by:
+  - ~occ-prop-gen-edit-actions.el~
+  - ~occ-prop-gen-checkout-actions.el~
+  - ~occ-prop-gen-misc-actions.el~
+
+* Clocking flow primitives
+- ~occ-do-clock-in~ is polymorphic over ~marker~, ~occ-tsk~, ~occ-ctsk~, ~occ-ctxual-tsk~, ~occ-ctx~.
+- ~occ-do-clock-in-if-not~, ~occ-do-clock-in-if-chg~, and timer wrappers coordinate context-aware clocking.
+- ~occ-do-clock-in-curr-ctx-if-not-timer-function~ is the idle/event timer callback.
+
+* Context and task collections
+- Collection builders:
+  - ~occ-tree-tsk-build~ (hierarchical)
+  - ~occ-obj-build-tsks~ (collection-level)
+- Tree helpers:
+  - ~tree-mapcar-nodes~, ~tree-mapc-nodes~, ~tree-remove-if-not-nodes~
+  - wrappers in ~occ-tree-tsk.el~.
+
+* Mode and keybinding configuration
+- ~occ-mode~: global minor mode.
+- ~occ-set-bindings~, ~occ-enable-mode-map~, ~occ-disable-mode-map~.
+- Prefix is configured by ~occ-prefix-key~.
+
+* Important variables and customizations
+- User customizations (~defcustom~):
+  - ~occ-prefix-key~
+  - ~occ-unnamed~
+  - ~occ-clockout-unassociable-to-unnamed~
+  - ~occ-completing-read-function~
+  - ~occ-clock-in-ctx-auto-select-if-only~
+  - ~occ-config-ineq-const-value~
+- Runtime and flow control:
+  - ~occ-idle-timeout~ (from utility/config paths)
+  - ~occ-config-clock-in~
+  - ~occ-list-select-ap-normal-keys~, ~occ-list-select-ap-transf-keys~
+  - ~occ-ignore-buffer-names~, ~occ-ignore-buffer-regexps~
+- Context history:
+  - ~*occ-clocked-ctxual-tsk-ctx-history*~
+  - ~*occ-tsk-current-ctx*~, ~*occ-tsk-previous-ctx*~
+
+* Extension points
+- Add a new context property: implement methods in ~occ-property-methods.el~ and add to ranking/edit/checkouts.
+- Add a new filter strategy: register static filter in ~occ-filter-config-initialize~.
+- Add new Helm actions: extend ~occ-helm-actions-config.el~ and action generators.
+- Add new collection types/specs: use collector APIs and collection constructors in ~occ.el~/~occ-obj-ctor.el~.
diff --git a/doc/codebase-audit.org b/doc/codebase-audit.org
new file mode 100644
index 0000000..304145e
--- /dev/null
+++ b/doc/codebase-audit.org
@@ -0,0 +1,47 @@
+#+TITLE: OCC Codebase Audit Notes
+#+PROPERTY: header-args :tangle no
+
+* Audit scope
+- Reviewed all top-level Emacs Lisp source files (~63 .el files~).
+- Reviewed existing docs under ~doc/~ and README.
+- Cross-checked TODO/BUG/Implement-it markers for backlog extraction.
+
+* High-level module map
+** Core bootstrap
+- ~occ.el~, ~occ-main.el~, ~occ-config.el~, ~occ-mode.el~, ~occ-version.el~
+
+** Selection + interaction
+- ~occ-select.el~, ~occ-helm.el~, ~occ-helm-method.el~, ~occ-helm-actions-config.el~
+
+** Clock orchestration
+- ~occ-clock.el~, ~occ-obj-clock-method.el~, ~occ-resolve-clock.el~, ~occ-unnamed.el~
+
+** Object model
+- ~occ-obj.el~, ~occ-obj-ctor.el~, ~occ-obj-accessor.el~, ~occ-obj-common.el~,
+  ~occ-obj-method.el~, ~occ-obj-simple.el~, ~occ-obj-utils.el~
+
+** Property subsystem
+- ~occ-prop-base.el~, ~occ-property-methods.el~, ~occ-property-editor.el~,
+  ~occ-prop-org.el~, ~occ-prop-intf.el~, ~occ-prop-utils.el~,
+  ops/generators under ~occ-prop-op-*.el~, ~occ-prop-gen-*.el~
+
+** Ranking + filtering
+- ~occ-rank.el~, ~occ-filter-base.el~, ~occ-filter-config.el~, ~occ-filter-op.el~
+
+** Task collections and trees
+- ~occ-tree.el~, ~occ-tree-tsk.el~, ~occ-list-tsk.el~, ~occ-tsk.el~
+
+** Utility/test/support
+- ~occ-util-common.el~, ~occ-util-method.el~, ~occ-print.el~, ~occ-debug-method.el~,
+  ~occ-statistics.el~, ~occ-test.el~, ~occ-scratch-space.el~
+
+* Audit conclusions
+1. The architecture is modular and extension-friendly (CLOS-style generic methods).
+2. Key user experience paths are implemented and usable (selection/clocking/property edits).
+3. There is significant backlog in command completion and documentation of edge cases.
+4. Existing docs are fragmented; this audit accompanies normalized docs in:
+   - ~doc/api-reference.org~
+   - ~doc/design-full.org~
+   - ~doc/usage.org~
+   - ~doc/installation.org~
+   - ~doc/pending.org~
diff --git a/doc/design-full.org b/doc/design-full.org
new file mode 100644
index 0000000..b06d3ff
--- /dev/null
+++ b/doc/design-full.org
@@ -0,0 +1,147 @@
+#+TITLE: OCC Design Document (Complete)
+#+PROPERTY: header-args :tangle no
+
+* 1. Problem statement
+OCC (Org Context Clock) attempts to keep org-clock aligned with the user’s
+*current working context* with minimal interruption. It addresses:
+- forgetting to clock in,
+- clocking into the wrong task after context switches,
+- reducing friction when many candidate tasks exist.
+
+* 2. System goals
+- Context-aware task ranking and selection.
+- Low-disruption prompting and optional automation.
+- Extensible property/matching model.
+- Safe fallback paths (unnamed tasks, property editor, resolve-clock integration).
+
+* 3. Architecture overview
+OCC has six major subsystems:
+
+1) Collection + task object model
+   - Builds task objects from org files (tree/list collections).
+   - Preserves parent/child relationships and subtree metadata.
+
+2) Context model
+   - Captures current buffer/file/VC state into ~occ-ctx~ objects.
+
+3) Property and ranking engine
+   - Property-specific predicates and ranking functions.
+   - Aggregates into overall rank with inherited/non-inherited components.
+
+4) Filtering pipeline
+   - Static filters converted into dynamic runtime filters.
+   - Separate display vs selectable closures.
+
+5) Interaction layer (Helm)
+   - Builds candidate sources, actions, keymaps.
+   - Enforces candidate selectability on final selection.
+
+6) Clocking orchestration
+   - Entry commands, timers, and event-driven clock switch logic.
+
+* 4. End-to-end data flow
+** 4.1 Initialization
+- ~occ-mode~ (or direct init) calls OCC setup.
+- Collector key selects the active spec and root org files.
+- Collections are built into task object structures.
+
+** 4.2 Trigger
+- User command (~occ-run~, ~occ-helm-match-select~, etc.) or timer callback
+  (~occ-do-clock-in-curr-ctx-if-not-timer-function~).
+
+** 4.3 Context capture
+- OCC constructs ~occ-ctx~ from current point/buffer state.
+
+** 4.4 Candidate construction
+- Context + collection + builder produce candidate task objects
+  (e.g. ~occ-ctxual-tsk~, ~occ-ctsk~).
+
+** 4.5 Rank + filter
+- Property ranks are computed and cached in rank tables.
+- Dynamic filters set both:
+  - display set (what is shown)
+  - selectable set (what can be accepted)
+
+** 4.6 Interaction
+- Helm renders candidates and actions.
+- RET respects ~selectable~; actions may still perform child/checkout/edit behavior.
+
+** 4.7 Clock transition
+- Selected task is clocked in via ~occ-do-clock-in~ polymorphic methods.
+- Hooks, history, and optional unnamed-task fallback are handled.
+
+* 5. Object model
+Main classes/structures (in ~occ-obj.el~ and constructors/accessors):
+- ~occ-ctx~: current user context.
+- ~occ-tsk~ family: task abstractions (marker-backed org headings).
+- ~occ-ctsk~, ~occ-ctxual-tsk~: task + context composite views.
+- ~occ-ranktbl~: rank cache and components.
+- Collection objects: tree and list forms.
+
+* 6. Ranking model
+Total rank uses:
+- inheritable property contribution,
+- non-inheritable contribution,
+- ancestor influence scaled by descendant weight.
+
+Additionally ~occ-obj-rank-max-decendent-with~ computes a subtree maximum useful
+for display-oriented strategies (e.g. top-level browsing without exploding list size).
+
+* 7. Property subsystem design
+A property in OCC typically defines:
+- detection (~occ-obj-impl-occ-prop-p~),
+- retrieval from context/user/object (~occ-obj-impl-get~),
+- comparison (~occ-obj-impl-prop=~),
+- ranking (~occ-obj-impl-rank~),
+- serialization (~to-org/from-org~),
+- list semantics (~list-p~),
+- checkout behavior (~occ-do-impl-checkout~),
+- inheritance semantics (~occ-obj-impl-inheritable-p~).
+
+This makes properties first-class extension points.
+
+* 8. Filtering subsystem design
+Static filters define:
+- points generation,
+- comparator,
+- default pivot,
+- optional rank functions for display/select.
+
+Dynamic filters keep closures for:
+- init/reset,
+- selectable filtering,
+- display filtering,
+- pivot increment/decrement.
+
+This design enables incremental narrowing and different display/select behaviors.
+
+* 9. Interaction design
+Helm integration includes:
+- custom source classes,
+- custom keymap,
+- configurable action packs.
+
+A key design behavior is read-only candidates: non-selectable items can be
+visible but cannot be accepted by RET.
+
+* 10. Timer/event design
+OCC uses context-change and idle timers to reduce manual clocking:
+- switches and editor events can trigger reevaluation,
+- quiet mode suppresses interruptions,
+- ignore lists prevent noisy/minibuffer/internal buffers from triggering transitions.
+
+* 11. Error handling and safety
+- Many operations check buffer live/read-only state and marker validity.
+- Some pathways intentionally return fallbacks (e.g., property editor,
+  unnamed task behavior) when direct association is not possible.
+
+* 12. Known design debt
+- Several placeholder commands still throw ~occ-error "Implement it."~.
+- Some TODO/BUG notes indicate rough edges in interactive flow,
+  source building, and recursion/window handling.
+
+* 13. Suggested next design increments
+1. Explicit browse mode with hierarchical collapse/expand actions.
+2. Split rank functions for browse vs clock-selection.
+3. Improve property docs and examples per built-in property.
+4. Formalize test matrix for filters/ranks/timers.
diff --git a/doc/installation.org b/doc/installation.org
new file mode 100644
index 0000000..739b00f
--- /dev/null
+++ b/doc/installation.org
@@ -0,0 +1,67 @@
+#+TITLE: OCC Installation Guide
+#+PROPERTY: header-args :tangle no
+
+* 1. Requirements
+From package metadata:
+- Emacs with Org (~org >= 9.6.9~ in package definition)
+- ~dash~
+- ~lotus-utils~, ~lotus-helm~
+- ~org-clock-unnamed-task~
+- ~org-clock-resolve-advanced~
+- ~org-clock-hooks~
+- ~org-clock-wrapper~
+- ~org-capture+~
+- ~activity~
+- ~org-clock-table-misc-lotus~
+- ~switch-buffer-functions~
+
+* 2. Installation methods
+** A) Via package.el / MELPA-style flow
+1. Ensure dependency repositories are available.
+2. Install ~occ~ package.
+3. Require ~occ-mode~ and enable OCC mode.
+
+** B) Via Cask for development
+1. Clone repository.
+2. Run Cask dependency install.
+3. Load files in Emacs and run tests/checks.
+
+Cask file defines package files and development dependencies.
+
+* 3. Minimal Emacs configuration example
+#+begin_src emacs-lisp
+(require 'occ)
+(require 'occ-mode)
+
+(setq occ-prefix-key "M-n")
+(occ-mode-global-allow)
+(occ-mode 1)
+
+;; Optional: automatically initialize default collector key
+(occ-insinuate (occ-collector-default-key))
+#+end_src
+
+* 4. Initial collection setup after install
+Run these commands:
+- ~occ-obj-build-spec~ (create a collector spec)
+- ~occ-add-org-file~ (add one or more org files)
+- ~occ-switch-default-key~ (if using multiple specs)
+
+Then test with:
+- ~occ-helm-match-select~
+- ~occ-run~
+
+* 5. Optional integrations
+- Resolve clock integration:
+  - ~occ-register-resolve-clock~
+- Unnamed task behavior:
+  - controlled via ~occ-unnamed~ and unnamed task subsystem
+
+* 6. Development/test dependencies
+From Cask development stanza:
+- ~f~, ~ecukes~, ~ert-runner~, ~el-mock~
+- plus runtime dependencies above.
+
+* 7. Notes
+- Some dependencies are from custom ecosystem packages (lotus/* org-clock-*).
+- For private/local package indexes, mirror corresponding recipes or source repos.
diff --git a/doc/pending.org b/doc/pending.org
new file mode 100644
index 0000000..fb5656c
--- /dev/null
+++ b/doc/pending.org
@@ -0,0 +1,72 @@
+#+TITLE: OCC Pending Issues and Features
+#+PROPERTY: header-args :tangle no
+
+* Pending issues (current codebase)
+This section captures unresolved implementation and stability items observed in
+code TODO/BUG markers and explicit ~occ-error "Implement it."~ placeholders.
+
+** 1) Unimplemented commands (user-facing)
+In ~occ-commands.el~, several interactive flows are placeholders:
+- ~occ-curr-tsk-continue-for~
+- ~occ-start-day~, ~occ-show-up~, ~occ-stop-day~, ~occ-pack-up~
+- ~occ-do-log-note~, ~occ-do-curr-tsk-log-note~
+- ~occ-do-clock-in-force~, ~occ-interrupt-clock-in~, ~occ-continue-prev~
+- ~occ-show-priority-ineql~
+
+** 2) Selection and Helm rough edges
+- TODO notes in ~occ-select.el~ indicate missing/partial documentation and edge behavior.
+- TODO/BUG notes in ~occ-helm-method.el~ mention undefined or incomplete source behavior and list editing work.
+- TODO in ~occ-util-method.el~ indicates action wiring inconsistencies in debug/launch paths.
+
+** 3) Property/editing debt
+- ~occ-prop-utils.el~ has explicit unimplemented read-property path.
+- ~occ-prop-base.el~ has TODO/BUG notes for multi-value property handling and legacy method-chain concerns.
+- ~occ-property-editor.el~ contains notes around recursive invocation and helm conditionality.
+
+** 4) Tree/collection and hierarchy concerns
+- ~occ-tree-tsk.el~ TODO for non-existing file/buffer cases and breadth limiting.
+- ~occ-obj-simple.el~ BUG notes around child insertion/order and list-select return behavior.
+
+** 5) Clocking/timer stability
+- ~occ-obj-clock-method.el~ has TODO/BUG notes around recursion, memory usage, and better prompts/flow explanations.
+- ~occ-util-common.el~ has TODO/BUG notes on buffer setup and unnamed clocking edge cases.
+
+** 6) Old backlog still present in docs
+~doc/todo.org~ includes long-lived items around:
+- helm stuck key states,
+- window configuration safety,
+- richer task/action workflows.
+
+* Pending features (recommended roadmap)
+
+** Feature group A: Browse mode for large hierarchies
+1. Add explicit *browse mode* distinct from selection mode.
+2. Show top-level/parent nodes by default; lazy-expand child lists.
+3. Provide subtree drill-down action with breadcrumb path.
+4. Keep parent non-selectable or provide "clock best child" action.
+
+** Feature group B: Ranking evolution
+1. Graded ranking by property priority bands.
+2. Separate rank strategies for display vs selection as first-class profile.
+3. Better visualization of why rank was assigned (per-property contributions).
+
+** Feature group C: Property ecosystem
+1. Complete and document built-in properties with examples.
+2. Add more project/workflow properties (schedule/deadline/repetition variants).
+3. Support robust multi-value property normalization and editing UI.
+
+** Feature group D: Reliability and UX
+1. Harden recursive-edit/minibuffer handling in timer paths.
+2. Improve helm source resilience and fallback behavior.
+3. Add consistent error classes/messages and recovery actions.
+
+** Feature group E: Testing and quality
+1. Expand ERT coverage for ranking, filters, and property comparators.
+2. Add regression tests for timer-triggered context changes.
+3. Add integration tests for selection + action + clock-in transitions.
+
+* Prioritization proposal
+1. Browse mode (high impact for large task trees).
+2. Timer/helm stability improvements.
+3. Property system cleanup + docs.
+4. Ranking explainability and test expansion.
diff --git a/doc/usage.org b/doc/usage.org
new file mode 100644
index 0000000..1cc2ffc
--- /dev/null
+++ b/doc/usage.org
@@ -0,0 +1,92 @@
+#+TITLE: OCC Usage Guide
+#+PROPERTY: header-args :tangle no
+
+* Overview
+OCC provides context-aware clock-in suggestions for Org headings and integrates
+with Helm for selection and task actions.
+
+* 1. Basic setup
+1. Load OCC and enable global allowance.
+2. Enable ~occ-mode~.
+3. Build/choose a collector spec and add org files.
+
+Example workflow (interactive commands):
+- ~M-x occ-mode-global-allow~
+- ~M-x occ-mode~
+- ~M-x occ-obj-build-spec~
+- ~M-x occ-add-org-file~
+
+* 2. Core command usage
+** Task selection commands
+- ~M-x occ-helm-match-select~
+  - Match-oriented list (good for immediate context-based clocking).
+- ~M-x occ-helm-list-select~
+  - General candidate list selection.
+- ~M-x occ-helm-list-debug-select~
+  - Inspect/experiment with actions.
+- ~M-x occ-helm-list-launch~
+  - Select candidate first, then launch chosen action.
+
+** Clock control commands
+- ~M-x occ-run~
+  - Normal OCC entry path (context-aware clocking flow).
+- ~M-x occ-clock-out~
+  - Clock out of current task.
+- ~M-x occ-curr-create-child~ / ~occ-curr-create-child-clock-in~
+  - Create child tasks from current task and optionally clock in.
+
+** Property editing
+- ~M-x occ-property-edit~
+  - Open property editor for current context/task relation.
+
+* 3. Keybindings in ~occ-mode~
+Default prefix key is ~M-n~ (customizable via ~occ-prefix-key~).
+Important bindings include:
+- ~M-n m s~: match select
+- ~M-n l s~: list select
+- ~M-n l e~: property edit
+- ~M-n t o~: clock out
+- ~M-n q~: keep quiet
+- ~M-n s ...~: collector/spec operations
+
+* 4. Collector/spec management
+Collectors define *which org files/tasks OCC works with*.
+Use:
+- ~occ-switch-default-key~
+- ~occ-reset-spec~
+- ~occ-obj-make-spec~
+- ~occ-add-to-spec~
+- ~occ-add-org-file~
+- ~occ-obj-build-spec~
+
+* 5. Typical daily workflow
+1. Start editor, ensure ~occ-mode~ is active.
+2. Run ~occ-run~ or ~occ-helm-match-select~ when switching work contexts.
+3. Accept recommended task (or child action for parent entries).
+4. Use ~occ-property-edit~ to improve context matching over time.
+5. Clock out at end with ~occ-clock-out~.
+
+* 6. Property-driven matching usage
+Built-in context methods include file/path/git-root style matching.
+Improve suggestions by setting these properties on headings:
+- ~currfile~
+- ~root~
+- ~git-branch~
+
+Use edit actions from selection UI or ~occ-property-edit~.
+
+* 7. Helm interaction behavior
+- Some candidates are visible but *not selectable*.
+- RET on non-selectable candidates shows readonly message.
+- Use alternate actions (e.g. child-clock-in) when available.
+
+* 8. Quiet mode and interruption control
+- ~occ-keep-quiet~: quick temporary quiet period.
+- ~occ-keep-quiet-for~: choose duration in minutes.
+During quiet mode, timer-triggered prompts are reduced.
+
+* 9. Troubleshooting quick checks
+- Verify collector/spec points to intended org files.
+- Verify current buffer is not in ignore list regexes.
+- Verify heading properties for context are present and normalized.
+- Use list-debug select to inspect available actions and candidate behavior.