Add comprehensive documentation and link from README

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]]

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~.

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~

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.

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.