rubik 0.4.1 → 0.5.0

data/lib/rubik/storage/vakanuvis/orientation.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require_relative "../layout"
+
+module Rubik
+  module Storage
+    module Vakanuvis
+      # Soğuk-başlangıç ve sıkıştırma sonrası yönelim enjeksiyonu (issue #340):
+      # Sistem istemi (system prompt) hiç şişirilmeden, oturumun ilk model
+      # çağrısından önce ve her bağlam sıkıştırması / budaması tamamlandığında
+      # kök konuşma geçmişine kısa, deterministik bir `role: "user"` yönelim
+      # iletisi eklenir. Kart yoksa (N == 0), kronikçi kapalıysa veya
+      # `subagents.vakanuvis.orientation == false` ise hiçbir şey enjekte
+      # edilmez. Kanca `ctx` içine tersiyle (`on_dispose`) kaydedilir (§1A).
+      module Orientation
+        DEFAULT_MAX_TOPICS = 10
+        HOOK_KEY = :vakanuvis_orientation_hook
+        TAG_OPEN = "<vakanuvis_orientation>"
+        TAG_CLOSE = "</vakanuvis_orientation>"
+        DEPTH_HINT = "Ask `vakanuvis(action: 'recall', query: '<2-3 terms>')` for depth."
+
+        # Oturum-içi durum ve terslenebilir kanca taşıyıcısı.
+        class Hook
+          attr_reader :harness
+
+          def initialize(harness, config: nil)
+            @harness = harness
+            @config = config
+            @session_oriented = false
+            @disposed = false
+          end
+
+          def dispose!
+            @disposed = true
+            @session_oriented = false
+          end
+
+          def disposed?
+            @disposed
+          end
+
+          def reset_session!
+            @session_oriented = false
+          end
+
+          def enabled?(override_config = nil)
+            return false if @disposed || @harness.nil? || @harness.stopped?
+
+            cfg = override_config || @config || @harness.config
+            return false unless Service.enabled?(cfg)
+
+            Layout.config_get(cfg, "subagents.vakanuvis.orientation", true) != false
+          end
+
+          def max_topics(override_config = nil)
+            cfg = override_config || @config || @harness.config
+            raw = Layout.config_get(cfg, "subagents.vakanuvis.orientation_max_topics", DEFAULT_MAX_TOPICS)
+            val = raw.to_i
+            val.positive? ? val : DEFAULT_MAX_TOPICS
+          end
+
+          def build_message(override_config = nil)
+            return nil unless enabled?(override_config)
+
+            excerpt = Orientation.format_excerpt(@harness, limit: max_topics(override_config))
+            return nil unless excerpt
+
+            { role: "user", content: excerpt }
+          end
+
+          def inject_session_start!(history, config: nil)
+            return nil unless history.is_a?(Array)
+
+            if history.any? { |m| Orientation.orientation_message?(m) }
+              @session_oriented = true
+              return nil
+            end
+            return nil if @session_oriented
+            return nil unless enabled?(config)
+
+            msg = build_message(config)
+            return nil unless msg
+
+            @session_oriented = true
+            Orientation.deduplicate_and_insert_start!(history, msg)
+          end
+
+          def inject_after_compaction!(history, config: nil)
+            return nil unless history.is_a?(Array)
+
+            Orientation.strip_orientation_messages!(history)
+            return nil unless enabled?(config)
+
+            msg = build_message(config)
+            return nil unless msg
+
+            @session_oriented = true
+            Orientation.insert_after_compaction!(history, msg)
+          end
+        end
+
+        module_function
+
+        # Kancayı `ctx` (veya child sub-context) içine tersiyle kaydeder (§1A).
+        # Kronikçi devre dışı bırakıldığında veya child dispose edildiğinde
+        # kanca otomatik olarak sökülür; reload döngülerinde yetim kanca kalmaz.
+        def register_hook(ctx, harness, config: nil, inverse_ctx: nil)
+          return nil unless ctx.respond_to?(:provide) && harness
+
+          cfg = config || harness.config
+          hook = Hook.new(harness, config: cfg)
+          ctx.provide(HOOK_KEY, hook)
+          target_ctx = inverse_ctx || ctx
+          cfg_inverse = wire_config_observer(ctx, hook, cfg)
+          if target_ctx.respond_to?(:on_dispose)
+            target_ctx.on_dispose do
+              cfg_inverse&.call
+              hook.dispose!
+              ctx.unprovide(HOOK_KEY) if ctx.respond_to?(:unprovide) && ctx.get(HOOK_KEY).equal?(hook)
+            end
+          end
+          hook
+        end
+
+        def wire_config_observer(ctx, hook, cfg)
+          return nil unless cfg.respond_to?(:on_change)
+
+          cfg.on_change("subagents.vakanuvis") do |_key, _val, _old|
+            next if hook.disposed?
+
+            if hook.enabled?(cfg)
+              ctx.provide(HOOK_KEY, hook) unless ctx.get(HOOK_KEY).equal?(hook)
+            elsif ctx.respond_to?(:unprovide) && ctx.get(HOOK_KEY).equal?(hook)
+              ctx.unprovide(HOOK_KEY)
+            end
+          end
+        end
+
+        # Coeffect üzerinden kancayı veya doğrudan VAKANUIS harness'ini çözer.
+        # VAKANUIS coeffect'i karşılanmamışsa nil döner.
+        def resolve_hook(context_or_manager, config: nil)
+          ctx = extract_context(context_or_manager)
+          return nil unless ctx
+
+          harness = Rubik::Coeffects.get(ctx, Rubik::Coeffects::VAKANUIS)
+          return nil unless harness.is_a?(Harness) && !harness.stopped?
+
+          cfg = config || harness.config
+          return nil unless Service.enabled?(cfg)
+          return nil if Layout.config_get(cfg, "subagents.vakanuvis.orientation", true) == false
+
+          hook = Rubik::Coeffects.get(ctx, HOOK_KEY)
+          return hook if hook.is_a?(Hook) && !hook.disposed? && hook.harness.equal?(harness)
+
+          register_hook(ctx, harness, config: cfg)
+        end
+
+        def reset_session!(context_or_manager)
+          ctx = extract_context(context_or_manager)
+          return false unless ctx
+
+          hook = Rubik::Coeffects.get(ctx, HOOK_KEY)
+          hook.reset_session! if hook.is_a?(Hook)
+          true
+        end
+
+        def inject_session_start!(history, context_or_manager, config: nil)
+          hook = resolve_hook(context_or_manager, config: config)
+          return nil unless hook
+
+          hook.inject_session_start!(history, config: config)
+        end
+
+        def inject_after_compaction!(history, context_or_manager, config: nil)
+          strip_orientation_messages!(history) if history.is_a?(Array)
+          hook = resolve_hook(context_or_manager, config: config)
+          return nil unless hook
+
+          hook.inject_after_compaction!(history, config: config)
+        end
+
+        # Aktif mem.* kartlarını [ref, row] sırasıyla listeler.
+        # Dönen çift: [lines_array, total_active_cards_count].
+        def topic_lines(store, limit: nil)
+          return [[], 0] unless store
+
+          bound = store.refs.select { |ref, _| Vocabulary.memory_ref?(ref) }
+          cards = store.list(type: "memory").select do |s|
+            s.status == Vocabulary::STATUS_ACTIVE && bound.value?(s.id)
+          end
+          return [[], 0] if cards.empty?
+
+          all_lines = cards.sort_by { |s| [bound.key(s.id), s.row] }.filter_map do |s|
+            record = store.get(type: "memory", id: s.id)
+            next unless record # list→get arası silme yarışı (review L2)
+
+            "- #{bound.key(s.id)} — #{s.title} — #{first_body_line(record)} — #{store.uri_for('memory', s.id)}"
+          end
+          total = all_lines.size
+          shown = limit ? all_lines.first(limit.to_i) : all_lines
+          [shown, total]
+        end
+
+        def first_body_line(record)
+          slice = record["body"].to_s.lines.map(&:strip).reject(&:empty?).first.to_s.slice(0, Harness::RECALL_BODY_SLICE)
+          slice.empty? ? "(no body)" : slice
+        end
+
+        # Aktif mem.* kartlarından deterministik [ref, row] sırasıyla en fazla
+        # `limit` satır üretir. Aktif kart yoksa (N == 0) nil döner.
+        def format_excerpt(harness, limit: DEFAULT_MAX_TOPICS)
+          store = harness.respond_to?(:store) ? harness.store : nil
+          lines, total = topic_lines(store, limit: limit)
+          return nil if lines.empty?
+
+          count_label = total > lines.size ? "#{lines.size} of #{total}" : lines.size.to_s
+          "#{TAG_OPEN}\nRecorded topics (#{count_label}):\n#{lines.join("\n")}\n#{DEPTH_HINT}\n#{TAG_CLOSE}"
+        end
+
+        def orientation_message?(msg)
+          return false unless msg.is_a?(Hash)
+
+          role = (msg[:role] || msg["role"]).to_s
+          return false unless role == "user"
+
+          content = (msg[:content] || msg["content"]).to_s
+          content.include?(TAG_OPEN) && content.include?(DEPTH_HINT)
+        end
+
+        def strip_orientation_messages!(history)
+          return history unless history.is_a?(Array)
+
+          history.reject! { |msg| orientation_message?(msg) }
+          history
+        end
+
+        # Oturum başında: sistem mesajı varsa hemen ardına (ilk user mesajından
+        # önce), yoksa dizinin başına yerleştirir. Eski kopyaları temizler.
+        def deduplicate_and_insert_start!(history, msg)
+          strip_orientation_messages!(history)
+          idx = first_non_system_index(history)
+          history.insert(idx, msg)
+          msg
+        end
+
+        # Sıkıştırma sonrasında: eski yönelim iletilerini siler ve yeni yönelim
+        # iletisini sistem mesajlarının hemen ardına deterministik olarak ekler.
+        def insert_after_compaction!(history, msg)
+          strip_orientation_messages!(history)
+          idx = first_non_system_index(history)
+          history.insert(idx, msg)
+          msg
+        end
+
+        def first_non_system_index(history)
+          idx = history.index do |m|
+            role = m.is_a?(Hash) ? (m[:role] || m["role"]).to_s : ""
+            role != "system"
+          end
+          idx || history.size
+        end
+
+        def extract_context(context_or_manager)
+          return nil unless context_or_manager
+
+          if context_or_manager.respond_to?(:context)
+            context_or_manager.context
+          elsif context_or_manager.respond_to?(:runtime_manager) && context_or_manager.runtime_manager.respond_to?(:context)
+            context_or_manager.runtime_manager.context
+          else
+            context_or_manager
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubik/storage/vakanuvis/service.rb

@@ -57,7 +57,11 @@ module Rubik
           )
           # Ömür (§2.7): child ctx'in cascade inverse'i worker'ı kapatır;
           # kuyruk FIFO'su drain olur, yarım kronik kalmaz.
-          child&.on_dispose { harness.shutdown }
+          child&.on_dispose do
+            harness.shutdown
+            ctx.unprovide(Rubik::Coeffects::VAKANUIS) if ctx.respond_to?(:unprovide) && ctx.get(Rubik::Coeffects::VAKANUIS).equal?(harness)
+          end
+          Orientation.register_hook(ctx, harness, config: config, inverse_ctx: child)
           harness.start!
           ctx.provide(Rubik::Coeffects::VAKANUIS, harness)
           context_or_manager.reconcile_all if context_or_manager.respond_to?(:reconcile_all)

data/lib/rubik/storage/vakanuvis/vocabulary.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Rubik
   module Storage
     module Vakanuvis
@@ -36,16 +38,45 @@ module Rubik
 
         module_function
 
+        def transliterate(text)
+          s = text.to_s.dup
+          s.gsub!(/[çÇ]/, "c")
+          s.gsub!(/[ğĞ]/, "g")
+          s.gsub!(/[ıİ]/, "i")
+          s.gsub!(/[öÖ]/, "o")
+          s.gsub!(/[şŞ]/, "s")
+          s.gsub!(/[üÜ]/, "u")
+          s.unicode_normalize(:nfd).gsub(/\p{M}/, "")
+        end
+
         # Deterministik slug: aynı metin ⇒ aynı slug ⇒ aynı ref (digest
         # makbuzlarının ve mem./wiki. ref'lerin yeniden oynatılabilirliği
         # buna dayanır). Yalnızca-rakam slug'a "n" öneki zorunlu: Store'un
         # çözümleyicisi "wiki.42" gibi iki parçalı tip.satır formlarını ref
         # alias'tan ÖNCE dener — çarpışma yanlış satırı ezmesi demekti.
+        # Unicode dönüştürme ve kısaltma/boşluk durumunda deterministik
+        # hash eki (issue #269) çakışmaları önler.
         def slug(text)
-          s = text.to_s.downcase.gsub(/[^a-z0-9]+/, "-")
+          raw = text.to_s
+          return "untitled" if raw.strip.empty?
+
+          trans = transliterate(raw)
+          lossy = trans.match?(/[^\x00-\x7F]/)
+
+          s = trans.downcase.gsub(/[^a-z0-9]+/, "-")
           s = s.delete_prefix("-") while s.start_with?("-")
           s = s.delete_suffix("-") while s.end_with?("-")
-          s = s[0, SLUG_MAX].to_s
+
+          hash = Digest::SHA256.hexdigest(raw)[0, 6]
+
+          return "untitled-#{hash}" if s.empty?
+
+          if s.length > SLUG_MAX || lossy
+            prefix = s[0, SLUG_MAX - 7].to_s
+            prefix = prefix.delete_suffix("-") while prefix.end_with?("-")
+            s = prefix.empty? ? "untitled-#{hash}" : "#{prefix}-#{hash}"
+          end
+
           s = s.delete_suffix("-") while s.end_with?("-")
           s = "n#{s}" if s.match?(/\A\d+\z/)
           s.empty? ? "untitled" : s

data/lib/rubik/storage/vakanuvis.rb

@@ -50,10 +50,16 @@ module Rubik
       # gereği notice YOK — sadece dmesg/stderr düzlemi.
       SUBSYSTEM = :storage
 
+      # Konu-adlı uyarıların SON İZİ buradır: iki havuz da patlarsa bile
+      # mesaj stderr'e düşer — kayıp iz yok (review #346 F2).
       def log_via(dmesg, level, message)
         dmesg.respond_to?(:log) ? dmesg.log(SUBSYSTEM, level, message) : Rubik::Log.send(level, SUBSYSTEM, message)
       rescue StandardError
-        Rubik::Log.warn(SUBSYSTEM, message)
+        begin
+          Rubik::Log.warn(SUBSYSTEM, message)
+        rescue StandardError
+          warn("[vakanuvis] #{message}")
+        end
       end
 
       def content_unchanged?(existing, title, body, tags, links, status)
@@ -74,4 +80,5 @@ require_relative "vakanuvis/wiki_skeleton"
 require_relative "vakanuvis/distill_gate"
 require_relative "vakanuvis/gate"
 require_relative "vakanuvis/harness"
+require_relative "vakanuvis/orientation"
 require_relative "vakanuvis/service"

data/lib/rubik/tools/builtins/lifecycle.rb

@@ -21,8 +21,7 @@ module Rubik
           type: "object",
           properties: {
             reason: { type: "string", description: "Optional explanation of why buffer is being applied (e.g. 'prior to running tests')" },
-            force: { type: "boolean",
-                     description: "If true, overwrites disk files even if modified externally by formatters (resolves [CONFLICT])" }
+            force: { type: "boolean", description: "If true, overwrites disk files even if modified externally by formatters (resolves [CONFLICT])" }
           }
         }
       )
@@ -42,8 +41,7 @@ module Rubik
                                   "(buffer.model_can_apply: false). The human operator will review and apply changes.")
         end
 
-        force = [true, "true"].include?(args["force"]) || [true, "true"].include?(args[:force]) ||
-                [true, "true"].include?(args["overwrite"]) || [true, "true"].include?(args[:overwrite])
+        force = [args["force"], args[:force], args["overwrite"], args[:overwrite]].intersect?([true, "true"])
         policy = force ? "overwrite" : nil
 
         if @buffer_manager.dirty?
@@ -66,16 +64,24 @@ module Rubik
                         "To force overwrite with your buffer changes, call: apply_buffer(force: true)\n" \
                         "Call read_file(path: \"#{c}\", reload: true) to inspect external changes or resolve."
           end
+          skipped = @buffer_manager.respond_to?(:last_skipped) ? (@buffer_manager.last_skipped || []) : []
+          skipped.each do |s|
+            path = s.is_a?(Hash) ? s[:path] : s.to_s
+            reason = s.is_a?(Hash) ? s[:reason] : "invalid path"
+            messages << "[SKIPPED] #{path}: discarded as invalid path (#{reason}) and NOT written to disk."
+          end
 
-          if applied.empty? && !conflicts.empty?
-            ToolOutput.error(messages.join("\n"))
-          elsif applied.empty?
-            # Inside the dirty? branch with zero applies and zero conflicts,
-            # every buffered entry was discarded as an invalid path
-            # (apply!'s garbage-skip) — the edits are NOT on disk, and citing
-            # an earlier apply here would be a lie.
-            "No unapplied buffer changes to write: the buffered entries were discarded as invalid paths and are NOT on disk. " \
-              "Re-check the target paths and buffer them again."
+          if applied.empty?
+            if conflicts.empty? && skipped.empty?
+              # Inside the dirty? branch with zero applies and zero conflicts,
+              # every buffered entry was discarded as an invalid path
+              # (apply!'s garbage-skip) — the edits are NOT on disk, and citing
+              # an earlier apply here would be a lie.
+              "No unapplied buffer changes to write: the buffered entries were discarded as invalid paths and are NOT on disk. " \
+                "Re-check the target paths and buffer them again."
+            else
+              ToolOutput.error(messages.join("\n"))
+            end
           else
             messages.join("\n")
           end
@@ -102,31 +108,18 @@ module Rubik
         params_schema: {
           type: "object",
           properties: {
-            target: {
-              type: "string",
-              enum: ["lsp", "test_runner", "linter", "command"],
-              description: "Runtime component type to repair or adapt"
-            },
-            language_or_type: {
-              type: "string",
-              description: "Language or service identifier (e.g., 'ruby', 'python', 'rust', 'go', 'zig', 'c', 'bash')"
-            },
+            target: { type: "string", enum: ["lsp", "test_runner", "linter", "command"], description: "Runtime component type to repair or adapt" },
+            language_or_type: { type: "string", description: "Language or service identifier (e.g., 'ruby', 'python', 'rust', 'go', 'zig', 'c', 'bash')" },
             proposed_command: {
               oneOf: [{ type: "string" },
-                      { type: "object", properties: { executable: { type: "string" },
-                                                      args: { type: "array", items: { type: "string" } } },
+                      { type: "object", properties: { executable: { type: "string" }, args: { type: "array", items: { type: "string" } } },
                         required: ["executable", "args"], additionalProperties: false },
                       { type: "array", items: { type: "string" }, minItems: 1 }],
               description: "Replacement command: a legacy string or, for LSP, {executable, args} / argv array. Omit to probe automatically."
             },
-            probe_args: {
-              type: "array", items: { type: "string" },
-              description: "Explicit non-mutating functional probe arguments appended to the exact proposed command; required for unknown executables"
-            },
-            auto_probe: {
-              type: "boolean",
-              description: "Whether to automatically probe system binaries and candidate commands (default: true)"
-            }
+            probe_args: { type: "array", items: { type: "string" },
+                          description: "Explicit non-mutating probe arguments appended to proposed command; required for unknown executables" },
+            auto_probe: { type: "boolean", description: "Whether to automatically probe system binaries and candidate commands (default: true)" }
           },
           required: ["target", "language_or_type"]
         }
@@ -154,25 +147,17 @@ module Rubik
         else
           proposed_cmd = raw_command.to_s.strip
         end
-        auto_probe = if args["auto_probe"].nil?
-                       args[:auto_probe].nil? || args[:auto_probe]
-                     else
-                       args["auto_probe"]
-                     end
+        auto_probe = args.fetch("auto_probe", args.fetch(:auto_probe, true))
 
         return ToolOutput.error("Target and language_or_type must be provided.") if target.empty? || lang.empty?
 
         # 1. Automatic Probing if proposed_cmd is not specified or auto_probe is requested
         if !command_provided?(proposed_cmd) && auto_probe
           candidate = case target
-                      when "lsp"
-                        Rubik::Runtime::Discovery.probe_lsp(lang, root_dir: @root_dir)
-                      when "test_runner"
-                        Rubik::Runtime::Discovery.discover_test_runners(root_dir: @root_dir, lang: lang).first
-                      when "linter"
-                        Rubik::Runtime::Discovery.discover_formatters(root_dir: @root_dir, lang: lang).first
-                      when "command"
-                        Rubik::Runtime::Discovery.binary_available?(lang) ? lang : nil
+                      when "lsp" then Rubik::Runtime::Discovery.probe_lsp(lang, root_dir: @root_dir)
+                      when "test_runner" then Rubik::Runtime::Discovery.discover_test_runners(root_dir: @root_dir, lang: lang).first
+                      when "linter" then Rubik::Runtime::Discovery.discover_formatters(root_dir: @root_dir, lang: lang).first
+                      when "command" then Rubik::Runtime::Discovery.binary_available?(lang) ? lang : nil
                       end
 
           if candidate
@@ -232,8 +217,18 @@ module Rubik
             @repair_scopes.delete([root_ctx, service_key]) if @repair_scopes[[root_ctx, service_key]].equal?(promotion_ctx)
             unless root_ctx.disposed?
               if previous_services.key?(service_key)
-                restored = target == "lsp" ? @lsp_manager&.clients&.[](lang) : nil
-                root_ctx.provide(service_key, restored || previous_services[service_key])
+                if target == "lsp"
+                  restored = @lsp_manager&.clients&.[](lang)
+                  active = restored && (!restored.respond_to?(:alive?) || restored.alive?) &&
+                           (!restored.respond_to?(:running?) || restored.running?)
+                  if active
+                    root_ctx.provide(service_key, restored)
+                  else
+                    root_ctx.unprovide(service_key)
+                  end
+                else
+                  root_ctx.provide(service_key, previous_services[service_key])
+                end
               else
                 root_ctx.unprovide(service_key)
               end

data/lib/rubik/tools/builtins/vakanuvis.rb

@@ -24,15 +24,12 @@ module Rubik
       DECLARATION = Declaration.new(
         name: "vakanuvis", aliases: ["chronicler"],
         description: "Ask the background chronicler (compiled knowledge in rubik://storage): " \
-                     "'recall' (deterministic digest over memory+wiki with source links — ask at task start " \
-                     "and after compaction), 'record' (persist durable knowledge as a memory card; the ONE " \
-                     "path for memory writes), 'forget' (supersede/purge a mem.* card or a note), 'digest' (queue an " \
-                     "async wiki compilation; returns a deterministic receipt, never blocks on the LLM), " \
-                     "'topics' (list recorded memory topics — orient before the first query), 'digest_status' " \
-                     "(is my queued digest pending, in flight, or done?). Notes (annal.*) are the chronicler's " \
-                     "evidence layer; memory cards are the durable conclusions you want recalled by default. " \
-                     "Hygiene: same topic, same session = one note — update it (or retire it with forget; " \
-                     "superseded rows keep a trace).",
+                     "'recall' (deterministic digest over memory+wiki with source links — ask at task start), " \
+                     "'record' (persist durable knowledge as a memory card; the ONE path for memory writes), " \
+                     "'forget' (supersede/purge a mem.* card or a note), 'digest' (queue an async wiki compilation; " \
+                     "returns a deterministic receipt, never blocks on the LLM), 'topics' (list recorded memory topics " \
+                     "— orient before the first query), 'digest_status' (is my queued digest pending, in flight, or done?). " \
+                     "Notes (annal.*) are the chronicler's evidence layer; memory cards are the durable conclusions you want recalled by default.",
         risk: :write, archetypes: [], write_grant: false,
         maestro_blocked: false, # storage emsali: kronikçi düzlemi kökte doğrudan
         params_schema: {
@@ -42,9 +39,11 @@ module Rubik
               type: "string", enum: ["recall", "record", "forget", "digest", "topics", "digest_status"],
               description: "Operation (default: 'recall')."
             },
-            query: { type: "string",
-                     description: "recall/digest: knowledge query. Recall is keyword-AND — every space-separated " \
-                                  "term must literally appear; retry with other-language synonyms when empty." },
+            query: {
+              type: "string",
+              description: "recall/digest: knowledge query. Recall is keyword-AND — use 2-3 core terms (every " \
+                           "space-separated term must literally appear); retry with other-language synonyms when empty."
+            },
             types: {
               type: "array", items: { type: "string", enum: ["memory", "wiki", "note"] },
               description: "recall: entity scopes to search (default: memory + wiki)."
@@ -52,9 +51,8 @@ module Rubik
             topic: { type: "string", description: "record: card topic — mints ref mem.<topic-slug> (upsert by topic)." },
             body: {
               type: "string",
-              description: "record: card body (markdown; end it with a Keywords: line of 5-10 TR+EN synonyms so " \
-                           "keyword-AND recall can find the card — a missing Keywords: line is auto-extracted " \
-                           "from the body at write time)."
+              description: "record: card body (markdown; end it with a Keywords: line of 5-10 TR+EN synonyms if you " \
+                           "can — a missing Keywords: line is auto-extracted from the body at write time)."
             },
             tags: {
               type: "array", items: { type: "string" },

data/lib/rubik/ui/capability.rb

@@ -10,12 +10,14 @@ module Rubik
     # Resolution order:
     #   1. RUBIK_TEST=1                     -> never (deterministic test output)
     #   2. NO_COLOR set                     -> never (https://no-color.org)
-    #   3. CLICOLOR_FORCE=1                 -> always (CI with color-capable logs)
+    #   3. CLICOLOR_FORCE set (not 0/false) -> always (CI with color-capable logs)
     #   4. ui.color config: always|never    -> explicit override
     #   5. output not a TTY                 -> never (pipe/redirect safety)
     #   6. TERM=dumb                        -> never
     #   7. Windows legacy conhost           -> try enabling VT, else never
     module Capability
+      FALSY_ENV_VALUES = ["0", "false", "no", "off"].freeze
+
       module_function
 
       # Strips ANSI SGR escape sequences from a string. Used on the recording
@@ -31,13 +33,16 @@ module Rubik
         case resolve_mode(io, config)
         when :always then true
         when :never then false
-        else io.respond_to?(:tty?) ? io.tty? : false
+        else
+          real_io = unwrap_tee(io)
+          real_io.respond_to?(:tty?) ? real_io.tty? : false
         end
       end
 
       # True when the target can animate a spinner line (real terminal only).
       def spinner?(io, config = nil)
-        color?(io, config) && io.respond_to?(:tty?) && io.tty? && interactive_env?
+        real_io = unwrap_tee(io)
+        color?(io, config) && real_io.respond_to?(:tty?) && real_io.tty? && interactive_env?
       end
 
       def interactive_env?
@@ -68,17 +73,26 @@ module Rubik
         io.targets.compact.find(&:tty?)
       end
 
+      def clicolor_force?
+        val = ENV.fetch("CLICOLOR_FORCE", nil)
+        return false if val.nil? || val.empty?
+
+        !FALSY_ENV_VALUES.include?(val.downcase)
+      end
+
       def resolve_mode(io, config)
         return :never if ENV["RUBIK_TEST"] == "1"
         return :never if ENV["NO_COLOR"] && !ENV["NO_COLOR"].to_s.empty?
-        return :always if ENV["CLICOLOR_FORCE"] && ENV["CLICOLOR_FORCE"].to_s == "1"
+        return :always if clicolor_force?
 
         cfg_mode = config&.fetch("ui.color", "auto").to_s.downcase if config
         return :always if cfg_mode == "always"
         return :never if cfg_mode == "never"
 
         return :never if ENV["TERM"] && ENV["TERM"].downcase == "dumb"
-        return :never unless io.respond_to?(:tty?) && io.tty?
+
+        real_io = unwrap_tee(io)
+        return :never unless real_io.respond_to?(:tty?) && real_io.tty?
 
         enable_windows_virtual_terminal_if_needed
         :auto

data/lib/rubik/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubik
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubik
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Özgür Ulukır
@@ -721,6 +721,7 @@ files:
 - lib/rubik/storage/vakanuvis/gate.rb
 - lib/rubik/storage/vakanuvis/harness.rb
 - lib/rubik/storage/vakanuvis/memory_steward.rb
+- lib/rubik/storage/vakanuvis/orientation.rb
 - lib/rubik/storage/vakanuvis/service.rb
 - lib/rubik/storage/vakanuvis/vocabulary.rb
 - lib/rubik/storage/vakanuvis/wiki_skeleton.rb